# JDBC

<!-- llms-txt-link: /llms.txt -->

> 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

- **Metrics**: `db.client.operation.duration`
- **Span attributes**: `db.connection_string`, `db.name`, `db.operation`, `db.sql.table`, `db.statement`, `db.system`, `db.user`, `peer.service`, `server.address`, `code.function`, `code.namespace`, `db.namespace`, `db.operation.batch.size`, `db.operation.name`, `db.query.summary`, `db.query.text`, `db.stored_procedure.name`, `db.system.name`, `error.type`, `service.peer.name`

## 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.&lt;key&gt;</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](https://google.github.io/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**: [/data/javaagent/instrumentations/jdbc/jdbc-8dfd60a1a5d0.json](/data/javaagent/instrumentations/jdbc/jdbc-8dfd60a1a5d0.json)
- **Explore**: [/java-agent/instrumentation/jdbc](/java-agent/instrumentation/jdbc)