# Semantic conventions for database client spans
Site [llms.txt](/llms.txt)
---
**Status**: [Stable][DocumentStatus], Unless otherwise specified.
- [Name](#name)
- [Database server address](#database-server-address)
- [Database server endpoints](#database-server-endpoints)
- [Service discovery](#service-discovery)
- [Span definition](#span-definition)
- [Notes and well-known identifiers for `db.system.name`](#notes-and-well-known-identifiers-for-dbsystemname)
- [Database client span duration](#database-client-span-duration)
- [Sanitization of `db.query.text`](#sanitization-of-dbquerytext)
- [Generating a summary of the query](#generating-a-summary-of-the-query)
- [Context propagation](#context-propagation)
- [SQL commenter](#sql-commenter)
- [Semantic conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies)
> [!IMPORTANT]
>
> Existing database instrumentations that are using
> [v1.24.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md)
> (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.
## Name
Database spans MUST follow the overall [guidelines for span names](/docs/specs/otel/trace/api/#span).
The **span name** SHOULD be `{db.query.summary}` if a summary is available.
If no summary is available, the span name SHOULD be `{db.operation.name} {target}`
provided that a (low-cardinality) `db.operation.name` is available (see below for
the exact definition of the [`{target}`](#target-placeholder) placeholder).
If a (low-cardinality) `db.operation.name` is not available, database span names
SHOULD default to the [`{target}`](#target-placeholder).
If neither `{db.operation.name}` nor `{target}` are available, span name SHOULD be `{db.system.name}`.
Semantic conventions for individual database systems MAY specify different span name format.
The `{target}` SHOULD describe the entity that the operation is performed against
and SHOULD adhere to one of the following values, provided they are accessible:
- `db.collection.name` SHOULD be used for operations on a specific database collection.
- `db.stored_procedure.name` SHOULD be used for operations on a specific stored procedure.
- `db.namespace` SHOULD be used for operations on a specific database namespace.
- `server.address` SHOULD be used for operations without a specific collection, stored procedure,
or namespace. If `server.port` is set, instrumentation SHOULD append it to `server.address`
using `:` as the separator.
If a corresponding `{target}` value is not available for a specific operation, the instrumentation SHOULD omit the `{target}`.
For example, for an operation describing SQL query on an anonymous table like `SELECT * FROM (SELECT * FROM table) t`, span name should be `SELECT`.
## Database 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. The value SHOULD remain unchanged
when the client discovers or selects different database servers.
When the client connects through an intermediary, `server.address` SHOULD identify the configured database
address behind the intermediary, if available.
Instrumentation SHOULD omit `server.address` if it cannot determine a safe, stable value from the client
configuration.
Instrumentation SHOULD record the server contacted for an operation in `network.peer.address` and
`network.peer.port` when available.
How instrumentation records `server.address` and `server.port` depends on whether the database client is
configured with database server endpoints or uses service discovery.
### Database server endpoints
When the client is configured with one or more database server endpoints, `server.address` SHOULD identify
those endpoints. This includes seed and contact-point lists, even if the client later discovers additional
topology from them.
A single endpoint SHOULD be a hostname, IP address, or UNIX socket path. Each endpoint in a list SHOULD be a
hostname or IP address, optionally followed by a port. IPv6 addresses that include a port MUST be enclosed in
square brackets. Multiple endpoints SHOULD be separated by commas without spaces. Instrumentation SHOULD NOT
perform reverse DNS lookups for IP addresses.
Instrumentation SHOULD preserve endpoint order when it is significant, and otherwise SHOULD sort the
endpoints lexicographically. Instrumentation MAY remove duplicate endpoints, but only when the duplicates
carry no semantic meaning.
After applying endpoint ordering and any permitted deduplication, instrumentation SHOULD include at most
the first five endpoints from the resulting list in `server.address`.
`[,...]/` MAY be used when all endpoints share a logical target that is
an unambiguous single path segment.
Record port information for database server endpoints as follows:
- If all endpoints use the default port, ports SHOULD be omitted from `server.address` and `server.port` SHOULD
NOT be set.
- If the client is configured with a single endpoint that uses a non-default port, the port SHOULD be omitted
from `server.address` and SHOULD be recorded in `server.port`.
- If the client is configured with multiple endpoints and any endpoint uses a non-default port, each endpoint's
port SHOULD be included in `server.address` and `server.port` SHOULD NOT be set.
Examples:
| Client configuration | `server.address` | `server.port` |
| --- | --- | --- |
| Single server on a non-default port: `db.example.com:15432` | `db.example.com` | `15432` |
| Multiple servers using the default port: `db-a.example.com,db-b.example.com` | `db-a.example.com,db-b.example.com` | Not set |
| Multiple servers using a shared port: `db-a.example.com,db-b.example.com` with port `6432` | `db-a.example.com:6432,db-b.example.com:6432` | Not set |
| Multiple servers using different ports: `db-a.example.com:5432,db-b.example.com:6432` | `db-a.example.com:5432,db-b.example.com:6432` | Not set |
### Service discovery
For service discovery, `server.address` SHOULD contain the canonical, low-cardinality value from the client
configuration. Depending on the client, this value identifies either a logical service or the discovery
service used to obtain database server endpoints. Ports for configured discovery service endpoints SHOULD
remain part of `server.address`. `server.port` SHOULD NOT be set.
Query and fragment components SHOULD be omitted unless they are part of the service identity.
Examples:
| Client configuration | `server.address` | `server.port` |
| --- | --- | --- |
| Service discovery through DNS SRV: `mongodb+srv://cluster.example.com` | `mongodb+srv://cluster.example.com` | Not set |
| Service discovery through ZooKeeper: `zookeeper://registry.example.com:2181/orders` | `zookeeper://registry.example.com:2181/orders` | Not set |
| Service discovery through Redis Sentinel: `sentinel-a.example.com:26379,sentinel-b.example.com:26379/mymaster` | `sentinel-a.example.com:26379,sentinel-b.example.com:26379/mymaster` | Not set |
## Span definition
**Status:** 
This span describes database client call.
Instrumentations SHOULD, when possible, record database spans that represent the logical database
operation as observed by the caller (such as client application).
When a database client provides higher-level convenience APIs for specific operations
(e.g., calling a stored procedure), which internally generate and execute a generic query,
it is RECOMMENDED to instrument the higher-level convenience APIs.
These often allow setting `db.operation.*` attributes, which usually are not
readily available at the generic query level.
**Span name** is covered in the [Name](/docs/specs/semconv/db/database-spans.md#name) section.
**Span duration** is covered in the [Database client span duration](/docs/specs/semconv/db/database-spans.md#database-client-span-duration) section.
**Span kind** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing
in-memory database calls.
It's RECOMMENDED to use `CLIENT` kind when database system being instrumented usually
runs in a different process than its client or when database calls happen over
instrumented protocol such as HTTP.
**Span status** SHOULD follow the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document.
Semantic conventions for individual systems SHOULD specify which values of `db.response.status_code`
classify as errors.
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`db.system.name`](/docs/specs/semconv/registry/attributes/db.md) |  | `Required` | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `softwareag.adabas`; `actian.ingres` [(see more)](#db-system-name-values) |
| [`db.collection.name`](/docs/specs/semconv/registry/attributes/db.md) |  | `Conditionally Required` [2] | string | The name of a collection (table, container) within the database. [3] | `public.users`; `customers` |
| [`db.namespace`](/docs/specs/semconv/registry/attributes/db.md) |  | `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`](/docs/specs/semconv/registry/attributes/db.md) |  | `Conditionally Required` [5] | string | The name of the operation or command being executed. [6] | `findAndModify`; `HMSET`; `SELECT` |
| [`db.response.status_code`](/docs/specs/semconv/registry/attributes/db.md) |  | `Conditionally Required` [7] | string | Database response status code. [8] | `102`; `ORA-17002`; `08P01`; `404` |
| [`error.type`](/docs/specs/semconv/registry/attributes/error.md) |  | `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`](/docs/specs/semconv/registry/attributes/server.md) |  | `Conditionally Required` [10] | int | Server port number. [11] | `80`; `8080`; `443` |
| [`db.operation.batch.size`](/docs/specs/semconv/registry/attributes/db.md) |  | `Recommended` | int | The number of database operations included in a batch operation. [12] | `2`; `3`; `4` |
| [`db.query.summary`](/docs/specs/semconv/registry/attributes/db.md) |  | `Recommended` [13] | string | Low cardinality summary of a database query. [14] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` |
| [`db.query.text`](/docs/specs/semconv/registry/attributes/db.md) |  | `Recommended` [15] | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` |
| [`db.stored_procedure.name`](/docs/specs/semconv/registry/attributes/db.md) |  | `Recommended` [17] | string | The name of a stored procedure within the database. [18] | `GetCustomer` |
| [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) |  | `Recommended` If applicable for this database system. | string | Peer address of the database node where the operation was performed. [19] | `10.1.2.80`; `/tmp/my.sock` |
| [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) |  | `Recommended` If and only if `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` |
| [`server.address`](/docs/specs/semconv/registry/attributes/server.md) |  | `Recommended` | string | The database address specified in the client configuration. [20] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`db.query.parameter.`](/docs/specs/semconv/registry/attributes/db.md) |  | `Opt-In` | string | A database query parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [21] | `someval`; `55` |
| [`db.response.returned_rows`](/docs/specs/semconv/registry/attributes/db.md) |  | `Opt-In` | int | Number of rows returned by the operation. [22] | `10`; `30`; `1000` |
**[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.operation.batch.size`:** Except for empty batch requests described below, a batch operation contains two
or more database operations explicitly submitted as separate operations in a single
client call, protocol message, or database command.
Requests to batch APIs that contain only one operation SHOULD be modeled as single
operations, not as batch operations.
A database call is not a batch operation solely because one operation accepts
multiple operands, such as keys, rows, documents, points, or other data elements,
including Redis [`MGET`](https://redis.io/docs/latest/commands/mget/) with
multiple keys.
In batch APIs that execute the same parameterized operation with parameter sets,
each parameter set represents one database operation for determining whether the
request is a batch operation. Requests with only one parameter set SHOULD be modeled
as single operations, not as batch operations.
`db.operation.batch.size` SHOULD be set to the number of operations in the batch.
It SHOULD NOT be set for non-batch operations.
A request to execute a batch operation with no operations SHOULD also be treated
as a batch operation, and `db.operation.batch.size` SHOULD be set to `0`.
**[13] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
**[14] `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](/docs/specs/semconv/db/database-spans.md#generating-a-summary-of-the-query)
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.
**[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/specs/semconv/db/database-spans.md#sanitization-of-dbquerytext).
Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/specs/semconv/registry/attributes/db.md)).
**[16] `db.query.text`:**
> [!WARNING]
> This attribute may contain large values. Applications should configure the OpenTelemetry SDK [attribute value limits](/docs/specs/otel/common/#attribute-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`](/docs/specs/semconv/db/database-spans.md#sanitization-of-dbquerytext).
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.
**[17] `db.stored_procedure.name`:** If operation applies to a specific stored procedure.
**[18] `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.
**[19] `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.
**[20] `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](/docs/specs/semconv/db/database-spans.md#database-server-address) for guidance and
examples.
**[21] `db.query.parameter.`:** If a query parameter has no name and instead is referenced only by index,
then `` SHOULD be the 0-based index.
`db.query.parameter.` SHOULD match
up with the parameterized placeholders present in `db.query.text`.
It is RECOMMENDED to capture the value as provided by the application
without attempting to do any case normalization or sanitization.
Instrumentations SHOULD NOT capture `db.query.parameter.` by default
since values may contain PII or sensitive details.
Application operators are expected to enable specific keys depending
on their privacy and security considerations.
`db.query.parameter.` SHOULD NOT be captured on batch operations.
Examples:
- For a query `SELECT * FROM users where username = %s` with the parameter `"jdoe"`,
the attribute `db.query.parameter.0` SHOULD be set to `"jdoe"`.
- For a query `"SELECT * FROM users WHERE username = %(userName)s;` with parameter
`userName = "jdoe"`, the attribute `db.query.parameter.userName` SHOULD be set to `"jdoe"`.
**[22] `db.response.returned_rows`:** The number of rows returned by the database operation as observed
by the instrumentation at the time the span ends.
The following attributes can be important for making sampling decisions
and SHOULD be provided **at span creation time** (if provided at all):
* [`db.collection.name`](/docs/specs/semconv/registry/attributes/db.md)
* [`db.namespace`](/docs/specs/semconv/registry/attributes/db.md)
* [`db.operation.name`](/docs/specs/semconv/registry/attributes/db.md)
* [`db.query.summary`](/docs/specs/semconv/registry/attributes/db.md)
* [`db.query.text`](/docs/specs/semconv/registry/attributes/db.md)
* [`db.system.name`](/docs/specs/semconv/registry/attributes/db.md)
* [`server.address`](/docs/specs/semconv/registry/attributes/server.md)
* [`server.port`](/docs/specs/semconv/registry/attributes/server.md)
---
`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](https://www.actian.com/databases/ingres/) |  |
| `aws.dynamodb` | [Amazon DynamoDB](https://aws.amazon.com/pm/dynamodb/) |  |
| `aws.redshift` | [Amazon Redshift](https://aws.amazon.com/redshift/) |  |
| `azure.cosmosdb` | [Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db) |  |
| `cassandra` | [Apache Cassandra](https://cassandra.apache.org/) |  |
| `clickhouse` | [ClickHouse](https://clickhouse.com/) |  |
| `cockroachdb` | [CockroachDB](https://www.cockroachlabs.com/) |  |
| `couchbase` | [Couchbase](https://www.couchbase.com/) |  |
| `couchdb` | [Apache CouchDB](https://couchdb.apache.org/) |  |
| `derby` | [Apache Derby](https://db.apache.org/derby/) |  |
| `elasticsearch` | [Elasticsearch](https://www.elastic.co/elasticsearch) |  |
| `firebirdsql` | [Firebird](https://www.firebirdsql.org/) |  |
| `gcp.spanner` | [Google Cloud Spanner](https://cloud.google.com/spanner) |  |
| `geode` | [Apache Geode](https://geode.apache.org/) |  |
| `h2database` | [H2 Database](https://h2database.com/) |  |
| `hbase` | [Apache HBase](https://hbase.apache.org/) |  |
| `hive` | [Apache Hive](https://hive.apache.org/) |  |
| `hsqldb` | [HyperSQL Database](https://hsqldb.org/) |  |
| `ibm.db2` | [IBM Db2](https://www.ibm.com/products/db2) |  |
| `ibm.informix` | [IBM Informix](https://www.ibm.com/products/informix) |  |
| `ibm.netezza` | [IBM Netezza](https://www.ibm.com/products/netezza) |  |
| `influxdb` | [InfluxDB](https://www.influxdata.com/) |  |
| `instantdb` | [Instant](https://www.instantdb.com/) |  |
| `intersystems.cache` | [InterSystems Caché](https://www.intersystems.com/products/cache/) |  |
| `mariadb` | [MariaDB](https://mariadb.org/) |  |
| `memcached` | [Memcached](https://memcached.org/) |  |
| `microsoft.sql_server` | [Microsoft SQL Server](https://www.microsoft.com/sql-server) |  |
| `mongodb` | [MongoDB](https://www.mongodb.com/) |  |
| `mysql` | [MySQL](https://www.mysql.com/) |  |
| `neo4j` | [Neo4j](https://neo4j.com/) |  |
| `opensearch` | [OpenSearch](https://opensearch.org/) |  |
| `oracle.db` | [Oracle Database](https://www.oracle.com/database/) |  |
| `other_sql` | Some other SQL database. Fallback only. |  |
| `postgresql` | [PostgreSQL](https://www.postgresql.org/) |  |
| `redis` | [Redis](https://redis.io/) |  |
| `sap.hana` | [SAP HANA](https://www.sap.com/products/technology-platform/hana/what-is-sap-hana.html) |  |
| `sap.maxdb` | [SAP MaxDB](https://maxdb.sap.com/) |  |
| `softwareag.adabas` | [Adabas (Adaptable Database System)](https://documentation.softwareag.com/?pf=adabas) |  |
| `sqlite` | [SQLite](https://www.sqlite.org/) |  |
| `teradata` | [Teradata](https://www.teradata.com/) |  |
| `trino` | [Trino](https://trino.io/) |  |
### Notes and well-known identifiers for `db.system.name`
The list above is a non-exhaustive list of well-known identifiers to be specified for `db.system.name`.
If a value defined in this list applies to the DBMS to which the request is sent, this value MUST be used.
If no value defined in this list is suitable, a custom value MUST be provided.
This custom value MUST be the name of the DBMS in lowercase and without a version number to stay consistent with existing identifiers.
It is encouraged to open a PR towards this specification to add missing values to the list, especially when instrumentations for those missing databases are written.
This allows multiple instrumentations for the same database to be aligned and eases analyzing for backends.
The value `other_sql` is intended as a fallback and MUST only be used if the DBMS is known to be SQL-compliant but the concrete product is not known to the instrumentation.
If the concrete DBMS is known to the instrumentation, its specific identifier MUST be used.
Backends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the `db.query.text`.
When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below.
## Database client span duration
Database client spans SHOULD, when possible, cover the duration of the
corresponding API call as observed by the caller (such as the client application).
For example, if a transient issue happened and was retried within this database call, the corresponding
span should cover the duration of the logical operation with all retries.
If there is any possibility for application code to not fully consume the database response
(and for the database client library to then have to clean up the database response asynchronously),
the database client span SHOULD NOT be ended in this cleanup phase,
and instead SHOULD end at some point after the initial call returns to the caller.
This avoids the span being ended asynchronously later on at a time
which is no longer directly associated with the application code which made the database request.
## Sanitization of `db.query.text`
The `db.query.text` SHOULD be collected by default only if there is sanitization that excludes sensitive information.
Sanitization SHOULD replace all literals with a placeholder value.
Such literals include, but are not limited to, String, Numeric, Date and Time,
Boolean, Interval, Binary, and Hexadecimal literals.
The placeholder value SHOULD be `?`, unless it already has a defined meaning in the given database system,
in which case the instrumentation MAY choose a different placeholder.
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.
[IN-clauses](https://wikipedia.org/wiki/SQL_syntax#Operators) MAY be collapsed during sanitization,
e.g. from `IN (?, ?, ?, ?)` to `IN (?)`, as this can help with extremely long IN-clauses,
and can help control cardinality for users who choose to (optionally) add `db.query.text` to their metric attributes.
When performing sanitization, instrumentation MAY truncate the sanitized value
for performance considerations (since sanitizing has a performance cost).
## Generating a summary of the query
The `db.query.summary` attribute can be used to capture a shortened representation
of the query. It SHOULD have low-cardinality and SHOULD NOT contain any dynamic
or sensitive data.
> [!NOTE]
>
> The `db.query.text` attribute is intended to identify individual queries. Even though
> it is sanitized if captured by default, it could still have high cardinality and
> might reach hundreds of lines.
>
> The `db.query.summary` is intended to provide a less granular grouping key that
> can be used as a span name or a metric attribute in common cases. It SHOULD
> only contain information that has a significant impact on the query, database,
> or application performance.
Instrumentation SHOULD set the query summary if it is readily available through
instrumentation hooks or other sources.
Otherwise:
- When instrumenting higher-level APIs that build queries internally - for example,
those that create a table or execute a stored procedure - instrumentations SHOULD
generate a `db.query.summary` from available operation(s) and target(s) using the
format described in this section.
- When instrumenting APIs that operate at the query level, instrumentations that
support query parsing SHOULD generate a query summary based on the `db.query.text`.
The summary SHOULD preserve the following parts of query in the order they were provided:
- operations such as SQL SELECT, INSERT, UPDATE, DELETE, and other commands
- operation targets such as collections, stored procedures, database names, etc
Instrumentations that support query parsing SHOULD parse the query and extract a
list of operations and targets from the query. It SHOULD set `db.query.summary`
attribute to the value formatted in the following way:
```
{operation1} {target1} {operation2} {target2} {target3} ...
```
Instrumentations SHOULD capture the values of operations and targets as provided
by the application without attempting to do any case normalization. If the operation
and target value is populated on `db.operation.name`, `db.collection.name`,
or other attributes, it SHOULD match the value used in the `db.query.summary`.
Instrumentations that parse the query to set `db.query.summary` SHOULD truncate the
summary to 255 characters (ensuring truncation does not occur within an operation
name or target).
**Examples**:
- Query that consist of a single operation:
```sql
SELECT *
FROM wuser_table
WHERE username = ?
```
the corresponding `db.query.summary` is `SELECT wuser_table`.
- Query that performs multiple operations:
```sql
INSERT INTO shipping_details
(order_id,
address)
SELECT order_id,
address
FROM orders
WHERE order_id = ?
```
the corresponding `db.query.summary` is `INSERT shipping_details SELECT orders`.
- Query that performs an operation that's applied to multiple collections:
```sql
SELECT *
FROM songs,
artists
WHERE songs.artist_id == artists.id
```
the corresponding `db.query.summary` is `SELECT songs artists`.
- Query that performs an operation on an anonymous table:
```sql
SELECT order_date
FROM (SELECT *
FROM orders o
JOIN customers c
ON o.customer_id = c.customer_id)
```
the corresponding `db.query.summary` is `SELECT SELECT orders customers`.
- Query that performs an operation on multiple collections with double-quotes or other punctuation:
```sql
SELECT *
FROM "song list",
'artists'
```
the corresponding `db.query.summary` is `SELECT "song list" 'artists'`.
- Stored procedure is executed using a convenience API such as one available in
[JDBC](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#prepareCall-java.lang.String-):
```java
connection.prepareCall("{call some_stored_procedure}");
```
the corresponding `db.query.summary` is `call some_stored_procedure`,
`db.query.text` is not populated. Note that `CALL` is the SQL standard
keyword to invoke a stored procedure.
- Stored procedure is executed using Microsoft SQL Server driver's convenience API
[Microsoft.Data.SqlClient](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlcommand.commandtype):
```csharp
var command = new SqlCommand();
command.CommandType = CommandType.StoredProcedure;
command.CommandText = "some_stored_procedure";
```
the corresponding `db.query.summary` is `EXECUTE some_stored_procedure`,
`db.query.text` is not populated. Note that Microsoft SQL Server does not
support the SQL Standard `CALL` keyword, but uses instead `EXECUTE`
to invoke a stored procedure.
Semantic conventions for individual database systems or specialized instrumentations
MAY specify a different `db.query.summary` format as long as produced summary remains
relatively short and its cardinality remains low comparing to the `db.query.text`.
## Context propagation
**Status**: [Development][DocumentStatus]
### SQL commenter
Instrumentations MAY propagate context using [SQL commenter](https://google.github.io/sqlcommenter/spec/) by injecting comments into SQL queries before execution. SQL commenter-based context propagation SHOULD NOT be enabled by default, but instrumentation MAY allow users to opt into it.
The instrumentation implementation SHOULD **append** the comment to the end of the query. Semantic conventions for individual database systems MAY specify different format, which may include different position, encoding, or schema, depending on the specific database system's requirements or preferences.
The instrumentation SHOULD allow users to pass a propagator to overwrite the global propagator. If no propagator is provided by the user, instrumentation SHOULD use the global propagator.
**Examples:**
- For a query `SELECT * FROM songs` with W3C TraceContext propagator:
```sql
SELECT * FROM songs /*traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',tracestate='congo%3Dt61rcWkgMzE%2Crojo%3D00f067aa0ba902b7'*/
```
Note that adding high cardinality comments, like `traceparent` and `tracestate`, to queries can impact the performance for some database systems, such as:
- Prepared statements in MySQL. See [this related issue](https://github.com/google/sqlcommenter/issues/284) for more details.
- Oracle and SQL Server for both prepared and non-prepared statements.
- For a query `SELECT * FROM songs` with a custom propagator that injects `service.name` into carrier where `service.name` is `shoppingcart`:
```sql
SELECT * FROM songs /*service.name='shoppingcart'*/
```
## Semantic conventions for specific database technologies
More specific Semantic Conventions are defined for the following database technologies:
* [AWS DynamoDB](dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
* [Cassandra](cassandra.md): Semantic Conventions for *Cassandra*.
* [Azure Cosmos DB](cosmosdb.md): Semantic Conventions for *Azure Cosmos DB*.
* [CouchDB](couchdb.md): Semantic Conventions for *CouchDB*.
* [Elasticsearch](elasticsearch.md): Semantic Conventions for *Elasticsearch*.
* [HBase](hbase.md): Semantic Conventions for *HBase*.
* [MongoDB](mongodb.md): Semantic Conventions for *MongoDB*.
* [Microsoft SQL Server](sql-server.md): Semantic Conventions for *Microsoft SQL Server*.
* [Redis](redis.md): Semantic Conventions for *Redis*.
* [SQL](sql.md): Semantic Conventions for *SQL* databases.
[DocumentStatus]: /docs/specs/otel/document-status/