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.
3 participants
Closes #8303