Automatic vs Manual Instrumentation for JDBC Connection Pool Exhaustion

Direct answer

Automatic instrumentation alone is usually not enough to tell a slow database from a depleted pool, and manually spanning every acquire/release is generally unsustainable at high throughput. The sustainable split is metrics for saturation and sampled traces for root cause.

Likely explanation vs. confirmed facts

Likely explanation: Intermittent exhaustion is hard to see because automatic JDBC spans measure query execution time, not the time a request thread spends waiting for a connection. If the pool library does not export its own metrics, the agent has no internal pool state—such as pending threads or queue depth—to attach.

Confirmed facts: The OpenTelemetry Java agent instruments JDBC calls and can produce spans around connection acquisition and release. However, coverage of pool internals varies by pool implementation and agent release; it is not guaranteed to expose active, idle, and pending counts for every library.

Steps for this case

1. Confirm the pool library and version. Check whether it exposes Micrometer or JMX metrics for active, idle, and pending connections plus acquire wait time.
2. If metrics exist, use automatic instrumentation plus a metrics bridge. Emit gauges for active/idle/pending and a histogram for acquire wait. This gives saturation visibility without per-request span overhead.
3. Add manual instrumentation only for gaps. If the library does not report a precise queue wait time or a custom pool identifier, add a targeted gauge or histogram—not a span per acquisition.
4. Sample traces by outcome, not by event. Use tail-based or parent-based sampling so that only slow or failed requests retain detailed connection timelines. Avoid per-event spans when the pool handles thousands of acquisitions per second.
5. Validate in staging under load. Compare pool metrics from the library/JMX against trace durations to determine whether waits occur before or during query execution. Inspect OpenTelemetry Collector or exporter logs for dropped spans or throttling.

Missing diagnostic detail

The specific connection pool library and version in use. Coverage differs significantly across HikariCP, Tomcat JDBC, Vibur, and others, so this detail determines whether a metrics bridge is sufficient or manual gauges are required.

Uncertainty and verification

Agent behavior and supported pool libraries change across OpenTelemetry Java agent releases; verify your exact agent version before relying on automatic pool metrics. High-cardinality manual attributes—such as thread names or stack traces—can overwhelm collectors and increase application CPU even at moderate sampling rates. Also, pool wait time measured only at the application layer may miss network or authentication delays that occur before the pool hands out a connection.