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 5 commits into
base: main
Choose a base branch
from
Open

Update jdbc doc with connection wrapping disclaimer #14884

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1177919
Update jdbc doc with connection wrapping disclaimer
jaydeluca Oct 3, 2025
d56d942
update wording
jaydeluca Oct 7, 2025
794a18c
pr review
jaydeluca Oct 16, 2025
35753ed
Merge branch 'main' into jdbc-docs
jaydeluca Oct 17, 2025
11eba34
simplify
jaydeluca Oct 19, 2025
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.
Copy link
Member

Choose a reason for hiding this comment

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

not sure if this is needed?


**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.
Copy link
Member

Choose a reason for hiding this comment

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

I'm not clear on the specifics reported in #8303 (comment)

but wondering if it's this:

https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/sql.md

[1] db.namespace: ...

A connection's currently associated database may change during its lifetime, e.g. from executing USE <database>.

If instrumentation is unable to capture the connection's currently associated database on each query without triggering an additional query to be executed (e.g. SELECT DATABASE()), then it is RECOMMENDED to fallback and use the database provided when the connection was established.

Instrumentation SHOULD document if db.namespace reflects the database provided when the connection was established.

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