JDBC
OpenTelemetry Java agent instrumentation
This instrumentation enables database client spans and database client metrics for JDBC operations. There is also a datasource instrumentation that creates spans for datasource connections (disabled by default). Note: The instrumentation unwraps pooled connections to cache metadata against the underlying physical connection; without proper unwrapping, repeated metadata extraction can cause performance degradation.
- Name:
jdbc - Scope:
io.opentelemetry.jdbc - Target versions:
Java 8+ - Library: https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html
Telemetry
When default
Spans
| Span kind | Attributes |
|---|---|
| CLIENT | db.connection_string (STRING), db.name (STRING), db.operation (STRING), db.sql.table (STRING), db.statement (STRING), db.system (STRING), db.user (STRING), peer.service (STRING), server.address (STRING) |
| INTERNAL | code.function (STRING), code.namespace (STRING), db.connection_string (STRING), db.name (STRING), db.system (STRING), db.user (STRING) |
When otel.semconv-stability.opt-in=database,service.peer
Metrics
| Metric | Instrument | Type | Unit | Description |
|---|---|---|---|---|
db.client.operation.duration | histogram | HISTOGRAM | s | Duration of database client operations. |
| Metric | Attributes |
|---|---|
db.client.operation.duration | db.namespace (STRING), db.query.summary (STRING), db.system.name (STRING) |
Spans
| Span kind | Attributes |
|---|---|
| CLIENT | db.namespace (STRING), db.operation.batch.size (LONG), db.operation.name (STRING), db.query.summary (STRING), db.query.text (STRING), db.stored_procedure.name (STRING), db.system.name (STRING), error.type (STRING), server.address (STRING), service.peer.name (STRING) |
| INTERNAL | code.function (STRING), code.namespace (STRING), db.namespace (STRING), db.system.name (STRING) |
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
otel.instrumentation.common.db.query-sanitization.enabled | boolean | true | Enables query sanitization for database queries. |
otel.instrumentation.common.peer-service-mapping | map | Used to specify a mapping from host names or IP addresses to peer services. | |
otel.instrumentation.jdbc-datasource.enabled | boolean | false | Enables instrumentation of JDBC datasource connections. |
otel.instrumentation.jdbc.experimental.capture-query-parameters | boolean | false | Sets whether the query parameters should be captured as span attributes named <code>db.query.parameter.<key></code>. 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.sqlcommenter.enabled | boolean | false | Enables augmenting queries with a comment containing the tracing information. See sqlcommenter for more info. WARNING: augmenting queries with tracing context will make query texts unique, which may have adverse impact on database performance. Consult with database experts before enabling. |
otel.instrumentation.jdbc.experimental.transaction.enabled | boolean | false | Enables experimental instrumentation to create spans for COMMIT and ROLLBACK operations. |
otel.instrumentation.jdbc.query-sanitization.enabled | boolean | true | Enables query sanitization for database queries. Takes precedence over otel.instrumentation.common.db.query-sanitization.enabled. |
Data
- JSON (latest): /data/javaagent/instrumentations/jdbc/latest.json
- JSON (pinned): /data/javaagent/instrumentations/jdbc/jdbc-8dfd60a1a5d0.json
- Explore: /java-agent/instrumentation/jdbc