tracking

func BuildMongoDBNamespace ¶ added in v0.12.0

func BuildMongoDBNamespace(database string) string

BuildMongoDBNamespace builds the db.namespace attribute for MongoDB. BuildMongoDBNamespace builds the db.namespace value for MongoDB according to OpenTelemetry conventions by returning the provided database name. If database is empty, an empty string is returned.

func BuildOracleNamespace ¶ added in v0.12.0

func BuildOracleNamespace(serviceName, sid, database string) string

BuildOracleNamespace builds the db.namespace attribute for Oracle. Per OTel spec, format is "{service_name}|{sid}|{database}". Returns empty string only when all inputs are empty. When any value is provided, returns the full format with empty placeholders for missing values. Examples: "PRODDB||", "|ORCL|", "||mydb", "PRODDB|ORCL|mydb"

func BuildPostgreSQLNamespace ¶ added in v0.12.0

func BuildPostgreSQLNamespace(database, schema string) string

BuildPostgreSQLNamespace builds the db.namespace attribute for PostgreSQL. Per OTel spec, this combines database and schema name as "{database}.{schema}". Returns empty string when schema is unknown (don't assume defaults like "public"). Only returns "{database}.{schema}" when both database and schema are provided.

func NewConnection ¶

func NewConnection(conn types.Interface, log logger.Logger, cfg *config.DatabaseConfig) types.Interface

NewConnection returns a database.Interface that wraps conn and records query/operation metrics and logs. The wrapper delegates all calls to the provided conn, uses conn.DatabaseType() NewConnection returns a types.Interface that wraps conn and records per-operation performance metrics, slow queries, and errors using the provided logger.

The wrapper uses conn.DatabaseType() as the vendor identifier and derives per-connection tracking settings from cfg via NewSettings.

func NewStatement ¶

func NewStatement(stmt types.Statement, log logger.Logger, vendor, query string, settings Settings) types.Statement

NewStatement creates a Statement wrapper that tracks performance for prepared statements. NewStatement wraps the provided statement with a tracking implementation that records execution metrics for Query, QueryRow, and Exec.

The returned types.Statement uses the supplied logger, vendor identifier, optional query string, and settings to control tracking behavior.

func NewTransaction ¶

func NewTransaction(tx types.Tx, log logger.Logger, vendor string, settings Settings) types.Tx

NewTransaction creates a Transaction wrapper that tracks performance for database transactions. NewTransaction creates a Transaction wrapper around the provided tx that records execution metrics for all transaction operations. The wrapper delegates calls to the given tx while capturing timing and error information, stores the provided logger, vendor, and settings, and initializes an internal Context used for tracking.

func RegisterConnectionPoolMetrics ¶ added in v0.12.0

func RegisterConnectionPoolMetrics(conn interface {
	Stats() (map[string]any, error)
}, vendor, serverAddress string, serverPort int, namespace string) func()

RegisterConnectionPoolMetrics registers ObservableGauges for connection pool metrics following OpenTelemetry semantic conventions v1.32.0.

This function should be called once per database connection during initialization.

Metrics registered per OTel spec: - db.client.connection.count{state="used"}: Active connections in use - db.client.connection.count{state="idle"}: Idle connections in pool - db.client.connection.idle.max: Maximum configured idle connections - db.client.connection.max: Maximum configured connections

Server Metadata Attributes: All metrics include server.address, server.port, and db.namespace (when available) in addition to db.system.name for full OTel compliance and correlation with operation metrics.

The gauges are updated automatically when metrics are collected (typically every 30s). Returns a cleanup function that can be called to unregister the metrics (optional).

This function uses graceful degradation - if any gauge fails to register, it continues with others and provides partial metrics coverage.

func SanitizeArgs ¶

func SanitizeArgs(args []any, maxLen int) []any

SanitizeArgs returns a sanitized copy of the input argument slice suitable for logging.

For string values the returned element is truncated to at most maxLen runes. For []byte values the returned element is the placeholder "<bytes len=N>" where N is the byte length. For all other values the element is formatted with "%v" and then truncated to at most maxLen runes. The returned slice preserves the input order and length. If args is empty, nil is returned.

func TrackDBOperation ¶

func TrackDBOperation(ctx context.Context, tc *Context, query string, args []any, start time.Time, rowsAffected int64, err error)

TrackDBOperation logs database operation performance metrics and errors. It provides centralized tracking for all database operations including queries, statements, and transactions. The function handles slow query detection, TrackDBOperation records metrics and emits a log event for a completed database operation.

TrackDBOperation is a no-op if tc or its Logger is nil. It records the operation's duration to request-scoped metrics, clamps the query string to the configured maximum length, and — when enabled — includes a sanitized form of parameters suitable for logging. If err is non-nil the error is logged (with sql.ErrNoRows logged at debug level); if there is no error and the duration exceeds the configured slow-query threshold a warning is emitted, otherwise a debug message is emitted.

The rowsAffected parameter represents the number of rows affected by write operations (INSERT, UPDATE, DELETE). For read operations (SELECT), pass 0.

func TruncateString ¶

func TruncateString(value string, maxLen int) string

TruncateString returns value truncated to at most maxLen characters. If maxLen <= 0 or value is already shorter than or equal to maxLen, the original string is returned. When maxLen <= 3 the function returns the first maxLen characters (no ellipsis); otherwise it returns the first TruncateString truncates value to at most maxLen runes, adding "..." when space allows to indicate truncation.

If maxLen <= 0 the original value is returned unchanged. If the string's rune count is less than or equal to maxLen the original value is returned. When maxLen <= 3 the function returns the first maxLen runes without an ellipsis. For maxLen > 3 the result contains the first (maxLen-3) runes followed by "...". Multi-byte characters are handled safely by operating on runes.