From 1177919869cba2ab6f74df6888c1fbf17cd2b36d Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Fri, 3 Oct 2025 17:31:33 -0400 Subject: [PATCH 1/2] Update jdbc doc with connection wrapping disclaimer --- docs/instrumentation-list.yaml | 1 + instrumentation/jdbc/README.md | 20 ++++++++++++++++++++ instrumentation/jdbc/metadata.yaml | 6 +++++- 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index 6ed491c25e9d..46fb111e749c 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -4735,6 +4735,7 @@ libraries: - name: jdbc description: | The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. + The instrumentation unwraps pooled connections to cache database metadata. If your connection pool doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation, causing higher CPU usage. There is also a "jdbc-datasource" instrumentation that creates spans for datasource connections, but is disabled by default due to the volume of telemetry produced. library_link: https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html source_path: instrumentation/jdbc diff --git a/instrumentation/jdbc/README.md b/instrumentation/jdbc/README.md index 428c78075f11..0cf46d934a7d 100644 --- a/instrumentation/jdbc/README.md +++ b/instrumentation/jdbc/README.md @@ -5,3 +5,23 @@ | `otel.instrumentation.jdbc.statement-sanitizer.enabled` | Boolean | `true` | Enables the DB statement sanitization. | | `otel.instrumentation.jdbc.experimental.capture-query-parameters` | Boolean | `false` | Enable the capture of query parameters as span attributes. Enabling this option disables the statement sanitization.

WARNING: captured query parameters may contain sensitive information such as passwords, personally identifiable information or protected health info. | | `otel.instrumentation.jdbc.experimental.transaction.enabled` | Boolean | `false` | Enables experimental instrumentation to create spans for COMMIT and ROLLBACK operations. | + +## Connection Pool Unwrapping + +The JDBC instrumentation unwraps pooled connections to cache database metadata efficiently. Most +connection pools support this by default. + +**Performance issue?** If unwrapping fails, database metadata is extracted on every operation +instead of being cached, causing higher CPU usage. To fix, ensure your connection pool supports +unwrapping: + +**Vibur DBCP example:** +```java +ds.setAllowUnwrapping(true); +``` + +**Custom wrappers:** Implement `java.sql.Wrapper` correctly to delegate `isWrapperFor()` and +`unwrap()` to the underlying connection. + +**Failover note:** Cached metadata uses the unwrapped connection object as the key. If your pool +reuses the same connection object after failover, telemetry may show stale host attributes. diff --git a/instrumentation/jdbc/metadata.yaml b/instrumentation/jdbc/metadata.yaml index f3c143e99490..bf337fc82bd7 100644 --- a/instrumentation/jdbc/metadata.yaml +++ b/instrumentation/jdbc/metadata.yaml @@ -2,7 +2,11 @@ description: > The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. - + + The instrumentation unwraps pooled connections to cache database metadata. If your connection pool + doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation, + causing higher CPU usage. + There is also a "jdbc-datasource" instrumentation that creates spans for datasource connections, but is disabled by default due to the volume of telemetry produced. library_link: https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html From d56d942a1485f1ab5d16b15e1fa06d19ba175cfc Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Tue, 7 Oct 2025 06:45:59 -0400 Subject: [PATCH 2/2] update wording --- docs/instrumentation-list.yaml | 2 +- instrumentation/jdbc/README.md | 11 +++++++---- instrumentation/jdbc/metadata.yaml | 8 +++++--- 3 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml index 46fb111e749c..ac37c2e70e49 100644 --- a/docs/instrumentation-list.yaml +++ b/docs/instrumentation-list.yaml @@ -4735,7 +4735,7 @@ libraries: - name: jdbc description: | The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. - The instrumentation unwraps pooled connections to cache database metadata. If your connection pool doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation, causing higher CPU usage. + The instrumentation requires unwrapping pooled connections (via java.sql.Wrapper) to correctly attribute database operations to the underlying connection and to cache metadata. If your connection pool doesn't support unwrapping, the instrumentation may have degraded performance or increased overhead with some JDBC drivers, as metadata extraction may result in database queries on every operation depending on driver implementation and caching behavior. There is also a "jdbc-datasource" instrumentation that creates spans for datasource connections, but is disabled by default due to the volume of telemetry produced. library_link: https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html source_path: instrumentation/jdbc diff --git a/instrumentation/jdbc/README.md b/instrumentation/jdbc/README.md index 0cf46d934a7d..9dff4e27b74b 100644 --- a/instrumentation/jdbc/README.md +++ b/instrumentation/jdbc/README.md @@ -8,12 +8,15 @@ ## Connection Pool Unwrapping -The JDBC instrumentation unwraps pooled connections to cache database metadata efficiently. Most +The JDBC instrumentation requires unwrapping pooled connections (via `java.sql.Wrapper`) to +correctly attribute database operations to the underlying connection and to cache metadata. Most connection pools support this by default. -**Performance issue?** If unwrapping fails, database metadata is extracted on every operation -instead of being cached, causing higher CPU usage. To fix, ensure your connection pool supports -unwrapping: +**Performance issue?** If unwrapping fails, the instrumentation may have degraded performance or +increased overhead with some JDBC drivers. Metadata extraction may result in database queries on +every operation (depending on driver implementation and caching behavior) instead of being cached, +and operations may be attributed to the wrong database connection. To fix, ensure your connection +pool supports unwrapping: **Vibur DBCP example:** ```java diff --git a/instrumentation/jdbc/metadata.yaml b/instrumentation/jdbc/metadata.yaml index bf337fc82bd7..d3049a5d53f6 100644 --- a/instrumentation/jdbc/metadata.yaml +++ b/instrumentation/jdbc/metadata.yaml @@ -3,9 +3,11 @@ description: > named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. - The instrumentation unwraps pooled connections to cache database metadata. If your connection pool - doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation, - causing higher CPU usage. + The instrumentation requires unwrapping pooled connections (via java.sql.Wrapper) to correctly + attribute database operations to the underlying connection and to cache metadata. If your connection + pool doesn't support unwrapping, the instrumentation may have degraded performance or increased + overhead with some JDBC drivers, as metadata extraction may result in database queries on every + operation depending on driver implementation and caching behavior. There is also a "jdbc-datasource" instrumentation that creates spans for datasource connections, but is disabled by default due to the volume of telemetry produced.