Enhancement/2026 01 metrics api integration

[takapi327]

Implementation Details

Integrate OpenTelemetry Semantic Conventions v1.39.0 compliant Metrics API, enabling measurement of database operation duration, returned row counts, and connection pool state. Internally uses otel4s and works on all platforms: JVM, JS, and Native.

When no OpenTelemetry backend is connected, metrics automatically become no-ops with zero performance impact.

Operation Metrics

Metric Name	Type	Description
db.client.operation.duration	Histogram (s)	Duration of database query execution
db.client.response.returned_rows	Histogram ({row})	Number of rows returned by a query

Connection Pool Metrics

Metric Name	Type	Description
db.client.connection.create_time	Histogram (s)	Time to create a new physical connection
db.client.connection.wait_time	Histogram (s)	Time waiting to acquire a connection from the pool
db.client.connection.use_time	Histogram (s)	Time between borrowing and returning a connection
db.client.connection.timeouts	Counter	Number of connection acquisition timeouts
db.client.connection.count	Gauge	Current number of connections (idle/used)
db.client.connection.idle.max	Gauge	Maximum number of idle connections allowed
db.client.connection.idle.min	Gauge	Minimum number of idle connections maintained
db.client.connection.max	Gauge	Maximum number of connections allowed
db.client.connection.pending_requests	Gauge	Number of requests waiting for a connection

Tracing Enhancements

• Span name generation compliant with OpenTelemetry Semantic Conventions (db.query.summary → {operation} {target} → fallback)
• Automatic sanitization of non-parameterized queries (replacing literal values with ?)
• IN clause collapsing (IN (?, ?, ?) → IN (?)) for cardinality control
• Error recording with error.type attribute and stack traces via recordException
• Customizable telemetry behavior through TelemetryConfig

Pull Request Checklist

• Wrote unit and integration tests
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code formatting by scalafmt (sbt scalafmtAll command execution)
• Add copyright headers to new files

References