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) |
When otel.semconv.exception.signal.preview=logs
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) |
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
java.common.database.sqlcommenter/development.enabled | boolean | false | Deprecated: use java.common.db.sqlcommenter/development.enabled instead. It is ignored under v3 preview. |
java.common.database.statement_sanitizer.enabled | boolean | true | Deprecated: use java.common.db.query_sanitization.enabled instead. It is ignored under v3 preview. |
otel.instrumentation.common.db-statement-sanitizer.enabled | boolean | true | Deprecated: use otel.instrumentation.common.db.query-sanitization.enabled instead. It is ignored under v3 preview and will be removed in 3.0. |
otel.instrumentation.common.db.query-sanitization.enabled | boolean | true | Enables query sanitization for database queries. |
otel.instrumentation.common.db.experimental.sqlcommenter.enabled | boolean | false | Enables augmenting queries with a comment containing tracing information. An instrumentation-specific setting takes precedence. See sqlcommenter for more info. WARNING: augmenting queries with tracing context will make query texts unique, which may have adverse impact on database performance. |
otel.instrumentation.common.peer-service-mapping | map | Used to specify a mapping from server addresses or configured targets to peer services. Configured targets containing commas or equals signs can only be mapped with declarative service_peer_mapping. | |
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 | Enables augmenting queries with a comment containing the tracing information. See sqlcommenter for more info. Overrides otel.instrumentation.common.db.experimental.sqlcommenter.enabled for this instrumentation; when unset, that setting applies. 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 | Enables query sanitization for database queries. Overrides otel.instrumentation.common.db.query-sanitization.enabled for this instrumentation; when unset, that setting applies. | |
otel.instrumentation.jdbc.statement-sanitizer.enabled | boolean | Deprecated: use otel.instrumentation.jdbc.query-sanitization.enabled instead. It is ignored under v3 preview and will be removed in 3.0. When unset, this setting falls back to otel.instrumentation.common.db.query-sanitization.enabled (including its deprecated aliases). |
Data
- JSON (latest): /data/javaagent/instrumentations/jdbc/latest.json
- JSON (pinned): /data/javaagent/instrumentations/jdbc/jdbc-f4b635337bcd.json
- Explore: /java-agent/instrumentation/jdbc