Skip to content

Update jdbc doc with connection wrapping disclaimer #14884

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+26 −1
Open

Update jdbc doc with connection wrapping disclaimer #14884

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/instrumentation-list.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this will require more careful wording. CPU usage isn' the real issue. The problem is that calling getMetaData may result in querying database (what this method does depends on the database driver, also the driver may cache the results). I'd suggests you to rephrase with emphasis on that instrumentation requires that connections can be unwrapped and that inability to unwrap may cause degraded performance or have increased overhead with some jdbc drivers. Below you also mention that unwrapping is needed for attributing work to correct connection. There was recently an issue with shardingsphere where we showed the wrong database for some queries.

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
Expand Down
20 changes: 20 additions & 0 deletions instrumentation/jdbc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. <p>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.
6 changes: 5 additions & 1 deletion instrumentation/jdbc/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down