Update jdbc doc with connection wrapping disclaimer #14884
Conversation
docs/instrumentation-list.yaml
Outdated
| - 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 was a problem hiding this comment.
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.
instrumentation/jdbc/README.md
Outdated
| **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. |
There was a problem hiding this comment.
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.namespacereflects the database provided when the connection was established.
instrumentation/jdbc/README.md
Outdated
| 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, 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: |
There was a problem hiding this comment.
The instrumentation unwraps pooled connections (via java.sql.Wrapper) to cache database metadata
against the underlying physical connection. Most connection pools support this by default.
In the case that a connection pool doesn't support this, caching is limited
to the wrapper instance, which typically changes each time a connection is retrieved from the pool.
This can result in repeated metadata extraction, potentially causing performance degradation.
instrumentation/jdbc/README.md
Outdated
| **Custom wrappers:** Implement `java.sql.Wrapper` correctly to delegate `isWrapperFor()` and | ||
| `unwrap()` to the underlying connection. |
3 participants
Closes #8303