Semantic conventions for database client metrics

Status: Mixed

Database operation
- Metric: db.client.operation.duration
Development
- Database response
  - Metric: db.client.response.returned_rows
- Connection pools

Important

Existing database instrumentations that are using v1.24.0 of this document (or prior):

SHOULD NOT change the version of the database conventions that they emit by default in their existing major version. Conventions include (but are not limited to) attributes, metric and span names, and unit of measure.
SHOULD introduce an environment variable OTEL_SEMCONV_STABILITY_OPT_IN in their existing major version as a comma-separated list of category-specific values (e.g., http, database, messaging). The list of values includes:
- database - emit the stable database conventions, and stop emitting the experimental database conventions that the instrumentation emitted previously.
- database/dup - emit both the experimental and stable database conventions, allowing for a phased rollout of the stable semantic conventions.
- The default behavior (in the absence of one of these values) is to continue emitting whatever version of the old experimental database conventions the instrumentation was emitting previously.
- Note: database/dup has higher precedence than database in case both values are present
SHOULD maintain (security patching at a minimum) their existing major version for at least six months after it starts emitting both sets of conventions.
MAY drop the environment variable in their next major version and emit only the stable database conventions.

Database operation

Metric: `db.client.operation.duration`

Status: Stable

This metric is recommended.

When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration.

This metric SHOULD be specified with ExplicitBucketBoundaries advisory parameter of [ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ].

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
`db.client.operation.duration`	Histogram	`s`	Duration of database client operations. [1]

[1]: Batch operations SHOULD be recorded as a single operation.

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`db.system.name`	`Required`	string	The database management system (DBMS) product as identified by the client instrumentation. [1]	`other_sql`; `softwareag.adabas`; `actian.ingres` (see more)
`db.collection.name`	`Conditionally Required` [2]	string	The name of a collection (table, container) within the database. [3]	`public.users`; `customers`
`db.namespace`	`Conditionally Required` If available.	string	The name of the database, fully qualified within the server address and port. [4]	`customers`; `test.users`
`db.operation.name`	`Conditionally Required` [5]	string	The name of the operation or command being executed. [6]	`findAndModify`; `HMSET`; `SELECT`
`db.response.status_code`	`Conditionally Required` [7]	string	Database response status code. [8]	`102`; `ORA-17002`; `08P01`; `404`
`error.type`	`Conditionally Required` If and only if the operation failed.	string	Describes a class of error the operation ended with. [9]	`timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`
`server.port`	`Conditionally Required` [10]	int	Server port number. [11]	`80`; `8080`; `443`
`db.query.summary`	`Recommended` [12]	string	Low cardinality summary of a database query. [13]	`SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id`
`db.stored_procedure.name`	`Recommended` [14]	string	The name of a stored procedure within the database. [15]	`GetCustomer`
`network.peer.address`	`Recommended` If applicable for this database system.	string	Peer address of the database node where the operation was performed. [16]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended` If and only if `network.peer.address` is set.	int	Peer port number of the network connection.	`65123`
`server.address`	`Recommended`	string	The database address specified in the client configuration. [17]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`db.query.text`	`Opt-In`	string	The database query being executed. [18]	`SELECT * FROM wuser_table where username = ?`; `SET mykey ?`

[1] db.system.name: The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the db.system.name is set to postgresql based on the instrumentation’s best knowledge.

[2] db.collection.name: If readily available and if a database call is performed on a single collection.

[3] db.collection.name: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

The collection name SHOULD NOT be extracted from db.query.text, when the database system supports query text with multiple collections in non-batch operations.

For batch operations, if the individual operations would all have the same db.collection.name when executed as non-batch operations, then that collection name SHOULD be used.

[4] db.namespace: If a database system has multiple namespace components, they SHOULD be concatenated from the most general to the most specific namespace component, using | as a separator between the components. Any missing components (and their associated separators) SHOULD be omitted. Semantic conventions for individual database systems SHOULD document what db.namespace means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

[5] db.operation.name: If readily available and if there is a single operation name that describes the database call.

[6] db.operation.name: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

The operation name SHOULD NOT be extracted from db.query.text, when the database system supports query text with multiple operations in non-batch operations.

If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space.

For batch operations, if the individual operations would all have the same db.operation.name when executed as non-batch operations, then that operation name SHOULD be used prepended by BATCH . Otherwise, db.operation.name SHOULD be BATCH or some other database system specific term if more applicable.

[7] db.response.status_code: If the operation failed and status code is available.

[8] db.response.status_code: The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. The value MAY use a standardized string representation of a numeric status code, if one exists, instead of the numeric code. The value MAY be a synthetic status provided by the client library rather than returned by the remote service. Semantic conventions for individual database systems SHOULD document what db.response.status_code means in the context of that system.

[9] error.type: The error.type SHOULD match the db.response.status_code returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. Instrumentations SHOULD document how error.type is populated.

[10] server.port: If server.address is set and the client is configured with a single database server endpoint that uses a non-default port.

[11] server.port: server.port SHOULD reflect the database port specified in the client configuration. It SHOULD NOT be derived from the server selected for an operation.

[12] db.query.summary: if available through instrumentation hooks or if the instrumentation supports generating a query summary.

[13] db.query.summary: The query summary describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries.

Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following Generating query summary section.

For batch operations, if the individual operations would all have the same db.query.summary when executed as non-batch operations, then that query summary SHOULD be used prepended by BATCH . Otherwise, db.query.summary SHOULD be BATCH or some other database system specific term if more applicable.

[14] db.stored_procedure.name: If operation applies to a specific stored procedure.

[15] db.stored_procedure.name: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.

For batch operations, if the individual operations would all have the same db.stored_procedure.name when executed as non-batch operations, then that stored procedure name SHOULD be used.

[16] network.peer.address: Semantic conventions for individual database systems SHOULD document whether network.peer.* attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.

[17] server.address: Instrumentation SHOULD set server.address to the database address specified in the client configuration. It SHOULD NOT derive the value from the server selected for an operation.

Warning

server.address MUST NOT contain credentials or other sensitive information.

See Database server address for guidance and examples.

[18] db.query.text:

Warning

This attribute may contain large values. Applications should configure the OpenTelemetry SDK attribute value limits. Instrumentations SHOULD additionally enforce an implementation-specific size limit before constructing or recording the value to avoid unbounded memory consumption.

For sanitization see Sanitization of db.query.text. For batch operations, if the individual operations would all have the same db.query.text when executed as non-batch operations, then that query text SHOULD be used. Otherwise, all of the individual query texts SHOULD be concatenated with separator ; or some other database system specific separator if more applicable. Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.

db.system.name has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
`actian.ingres`	Actian Ingres
`aws.dynamodb`	Amazon DynamoDB
`aws.redshift`	Amazon Redshift
`azure.cosmosdb`	Azure Cosmos DB
`cassandra`	Apache Cassandra
`clickhouse`	ClickHouse
`cockroachdb`	CockroachDB
`couchbase`	Couchbase
`couchdb`	Apache CouchDB
`derby`	Apache Derby
`elasticsearch`	Elasticsearch
`firebirdsql`	Firebird
`gcp.spanner`	Google Cloud Spanner
`geode`	Apache Geode
`h2database`	H2 Database
`hbase`	Apache HBase
`hive`	Apache Hive
`hsqldb`	HyperSQL Database
`ibm.db2`	IBM Db2
`ibm.informix`	IBM Informix
`ibm.netezza`	IBM Netezza
`influxdb`	InfluxDB
`instantdb`	Instant
`intersystems.cache`	InterSystems Caché
`mariadb`	MariaDB
`memcached`	Memcached
`microsoft.sql_server`	Microsoft SQL Server
`mongodb`	MongoDB
`mysql`	MySQL
`neo4j`	Neo4j
`opensearch`	OpenSearch
`oracle.db`	Oracle Database
`other_sql`	Some other SQL database. Fallback only.
`postgresql`	PostgreSQL
`redis`	Redis
`sap.hana`	SAP HANA
`sap.maxdb`	SAP MaxDB
`softwareag.adabas`	Adabas (Adaptable Database System)
`sqlite`	SQLite
`teradata`	Teradata
`trino`	Trino

Development

Status: Development

Database response

The following metric instruments describe database query response.

Metric: `db.client.response.returned_rows`

This metric is recommended.

This metric SHOULD be specified with ExplicitBucketBoundaries advisory parameter of [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000].

Explaining bucket configuration:

1, 2, 5, 10, 50, 100: These buckets are useful for capturing scenarios where only a small number of items are returned. Such small queries are common in real-time or interactive applications where performance and quick responses are critical.
200, 500, 1000: These values represent typical workloads where moderate amounts of data are returned in each query.
2000, 5000: These boundaries capture scenarios where the query returns large datasets. These larger page sizes can potentially increase memory or CPU usage and may lead to longer query execution times, making it important to track performance in these ranges.
10000: This boundary is included to capture rare, very large response sizes. Such queries can put significant strain on system resources, including memory, CPU, and network bandwidth, and can often lead to performance issues such as high latency or even network drops.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
`db.client.response.returned_rows`	Histogram	`{row}`	The actual number of records returned by the database operation.

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`db.system.name`	`Required`	string	The database management system (DBMS) product as identified by the client instrumentation. [1]	`other_sql`; `softwareag.adabas`; `actian.ingres` (see more)
`db.collection.name`	`Conditionally Required` [2]	string	The name of a collection (table, container) within the database. [3]	`public.users`; `customers`
`db.namespace`	`Conditionally Required` If available.	string	The name of the database, fully qualified within the server address and port. [4]	`customers`; `test.users`
`db.operation.name`	`Conditionally Required` [5]	string	The name of the operation or command being executed. [6]	`findAndModify`; `HMSET`; `SELECT`
`db.response.status_code`	`Conditionally Required` [7]	string	Database response status code. [8]	`102`; `ORA-17002`; `08P01`; `404`
`error.type`	`Conditionally Required` If and only if the operation failed.	string	Describes a class of error the operation ended with. [9]	`timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`
`server.port`	`Conditionally Required` [10]	int	Server port number. [11]	`80`; `8080`; `443`
`db.query.summary`	`Recommended` [12]	string	Low cardinality summary of a database query. [13]	`SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id`
`network.peer.address`	`Recommended` If applicable for this database system.	string	Peer address of the database node where the operation was performed. [14]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended` If and only if `network.peer.address` is set.	int	Peer port number of the network connection.	`65123`
`server.address`	`Recommended`	string	The database address specified in the client configuration. [15]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`db.query.text`	`Opt-In`	string	The database query being executed. [16]	`SELECT * FROM wuser_table where username = ?`; `SET mykey ?`