groups: - id: trace.db.common.minimal extends: attributes.db.client.minimal type: attribute_group brief: This group defines the attributes used to perform database client calls. attributes: # TODO: add db.system.name once https://github.com/open-telemetry/build-tools/issues/192 is possible # - ref: db.system.name # sampling_relevant: true - ref: db.operation.name sampling_relevant: true requirement_level: conditionally_required: > If readily available and if there is a single operation name that describes the database call. - ref: db.operation.batch.size - ref: server.address sampling_relevant: true - ref: server.port sampling_relevant: true - id: trace.db.common.query extends: attributes.db.client.with_query type: attribute_group brief: This group defines the attributes used to perform database client calls. attributes: - ref: server.address sampling_relevant: true - ref: server.port sampling_relevant: true - ref: db.operation.batch.size - ref: db.response.returned_rows - ref: db.query.text sampling_relevant: true requirement_level: recommended: > 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/database/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/attributes-registry/db.md)). - ref: db.query.summary sampling_relevant: true - ref: db.query.parameter requirement_level: opt_in - id: trace.db.common.query_and_collection extends: attributes.db.client.with_query_and_collection type: attribute_group brief: This group defines the attributes used to perform database client calls. attributes: - ref: db.collection.name sampling_relevant: true - ref: db.operation.name sampling_relevant: true - ref: db.operation.batch.size - ref: server.address sampling_relevant: true - ref: server.port sampling_relevant: true - ref: db.response.returned_rows - ref: db.query.text sampling_relevant: true requirement_level: recommended: > 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/database/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/attributes-registry/db.md)). - ref: db.query.summary sampling_relevant: true - ref: db.query.parameter requirement_level: opt_in - id: trace.db.common.full type: attribute_group brief: This group documents attributes that describe database call along with network information. extends: trace.db.common.query_and_collection attributes: - ref: network.peer.address brief: Peer address of the database node where the operation was performed. requirement_level: recommended: If applicable for this database system. note: > 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. - ref: network.peer.port requirement_level: recommended: if and only if `network.peer.address` is set. - ref: db.system.name sampling_relevant: true # TODO: Not adding to the minimal because of https://github.com/open-telemetry/build-tools/issues/192 requirement_level: required - ref: db.namespace sampling_relevant: true requirement_level: conditionally_required: If available. - ref: db.stored_procedure.name requirement_level: recommended: If operation applies to a specific stored procedure. - id: span.db.client type: span stability: release_candidate brief: This span describes database client call. note: | Instrumentations SHOULD, when possible, record database spans that cover the duration of the corresponding API call as if it was observed by the caller (such as 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. 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/database/database-spans.md#name) 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** Refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. Semantic conventions for individual systems SHOULD specify which values of `db.response.status_code` classify as errors. span_kind: client extends: trace.db.common.full attributes: - ref: db.response.returned_rows requirement_level: opt_in # experimental attributes must be opt-in stable spans # TODO (trask) make this recommended once it is stable - id: span.db.sql_server.client type: span stability: release_candidate extends: span.db.sql.client span_kind: client brief: > Spans representing calls to Microsoft SQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). note: | `db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true brief: > The database associated with the connection, qualified by the instance name. note: | When connected to a default instance, `db.namespace` SHOULD be set to the name of the database. When connected to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances), `db.namespace` SHOULD be set to the combination of instance and database name following the `{instance_name}|{database_name}` pattern. A connection's currently associated database may change during its lifetime, e.g. from executing `USE `. If instrumentation is unable to capture the connection's currently associated database on each query without triggering an additional query to be executed (e.g. `SELECT DB_NAME()`), then it is RECOMMENDED to fallback and use the database provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the database provided when the connection was established. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ["instance1.products", "customers"] - ref: db.response.status_code brief: > [Microsoft SQL Server error](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) number represented as a string. note: > Microsoft SQL Server does not report SQLSTATE. Instrumentations SHOULD use [error severity](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-error-severities) returned along with the status code to determine the status of the span. Response codes with severity 11 or higher SHOULD be considered errors. examples: ["102", "40020"] - id: span.db.postgresql.client type: span stability: release_candidate extends: span.db.sql.client span_kind: client brief: > Spans representing calls to a PostgreSQL database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). note: | `db.system.name` MUST be set to `"postgresql"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true brief: > The schema associated with the connection, qualified by the database name. note: | `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}|{schema}` pattern. If either `{database}` or `{schema}` is unavailable, `db.namespace` SHOULD be set to the other (without any `|` separator). A connection's currently associated database may change during its lifetime, e.g. from executing `SET search_path TO `. If the search path has multiple schemas, the first schema in the search path SHOULD be used. If instrumentation is unable to capture the connection's currently associated schema on each query without triggering an additional query to be executed (e.g. `SELECT current_schema()`), then it is RECOMMENDED to fallback and use the schema provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the schema provided when the connection was established. Instrumentation MAY use the user name when the connection was established as a stand-in for the schema name. Instrumentation SHOULD document if `db.namespace` reflects the user provided when the connection was established. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ["mydatabase.products", "mydatabase.customers"] - ref: db.response.status_code brief: > [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). note: > PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE). Response codes of "Class 02" or higher SHOULD be considered errors. examples: ["08000", "08P01"] - id: span.db.mysql.client type: span stability: release_candidate extends: span.db.sql.client span_kind: client brief: > Spans representing calls to a MySQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). note: | `db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true brief: The database associated with the connection. note: | A connection's currently associated database may change during its lifetime, e.g. from executing `USE `. If instrumentation is unable to capture the connection's currently associated database on each query without triggering an additional query to be executed (e.g. `SELECT DATABASE()`), then it is RECOMMENDED to fallback and use the database provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the database provided when the connection was established. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ["products", "customers"] - ref: db.response.status_code brief: > [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string. note: > MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All MySQL error codes SHOULD be considered errors. examples: ["1005", "MY-010016"] - id: span.db.mariadb.client type: span stability: release_candidate extends: span.db.sql.client span_kind: client brief: > Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/README.md). note: > `db.system.name` MUST be set to `"mariadb"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true brief: The database associated with the connection. note: | A connection's currently associated database may change during its lifetime, e.g. from executing `USE `. If instrumentation is unable to capture the connection's currently associated database on each query without triggering an additional query to be executed (e.g. `SELECT DATABASE()`), then it is RECOMMENDED to fallback and use the database provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the database provided when the connection was established. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ["products", "customers"] - ref: db.response.status_code brief: > [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. note: > MariaDB uses vendor-specific error codes on all errors and reports [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases. MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations SHOULD set the `db.response.status_code` to this known error code. When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be considered errors. When SQLSTATE is not available, all MariaDB error codes SHOULD be considered errors. examples: ["1008", "3058"] - id: span.db.cassandra.client type: span span_kind: client stability: development extends: trace.db.common.query_and_collection brief: > Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: | `db.system.name` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.namespace sampling_relevant: true brief: The keyspace associated with the session. examples: ["mykeyspace"] requirement_level: conditionally_required: If available. - ref: cassandra.page.size - ref: cassandra.consistency.level - ref: db.collection.name brief: The name of the Cassandra table that the operation is acting upon. note: | 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 are known to have the same collection name then that collection name SHOULD be used. - ref: cassandra.query.idempotent - ref: cassandra.speculative_execution.count - ref: cassandra.coordinator.id - ref: cassandra.coordinator.dc - ref: network.peer.address brief: Peer address of the database node where the operation was performed. requirement_level: recommended note: > If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. - ref: network.peer.port requirement_level: recommended: if and only if `network.peer.address` is set. - ref: db.response.status_code brief: > [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. note: > All Cassandra protocol error codes SHOULD be considered errors. examples: ["102", "40020"] - id: span.db.hbase.client type: span span_kind: client stability: development extends: trace.db.common.minimal brief: > Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: | `db.system.name` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.namespace sampling_relevant: true brief: The HBase namespace. requirement_level: conditionally_required: If applicable. examples: ['mynamespace'] - ref: db.collection.name sampling_relevant: true brief: The HBase table name. requirement_level: conditionally_required: If applicable. note: > It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name. examples: ['mytable', 'ns:table'] - ref: db.operation.name note: | 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 are known to have the same operation name then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH`. requirement_level: required - ref: db.response.status_code brief: > Protocol-specific response code recorded as a string. examples: ["200", "409", "14"] requirement_level: conditionally_required: If response was received. - id: span.db.couchdb.client type: span span_kind: client stability: development extends: trace.db.common.minimal brief: > Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: | `db.system.name` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.operation.name sampling_relevant: true brief: > The HTTP method + the target REST route. examples: ['GET /{db}/{docid}'] note: > In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). requirement_level: conditionally_required: If readily available. - ref: db.namespace sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note - ref: db.response.status_code brief: > The HTTP response code returned by the Couch DB recorded as a string. note: > HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. examples: ["200", "201", "429"] requirement_level: conditionally_required: If response was received and the HTTP response code is available. - id: span.db.redis.client type: span stability: development span_kind: client extends: trace.db.common.minimal brief: > Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: | `db.system.name` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up looking confusing. attributes: - ref: db.namespace sampling_relevant: true brief: > The [database index] associated with the connection, represented as a string. requirement_level: conditionally_required: If and only if it can be captured reliably. note: | A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. If instrumentation is unable to capture the connection's currently associated database index on each query without triggering an additional query to be executed, then it is RECOMMENDED to fallback and use the database index provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the database index provided when the connection was established. examples: ["0", "1", "15"] - ref: db.operation.name brief: > The Redis command name. examples: ["HMSET", "GET", "SET"] note: > It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. For [transactions and pipelined calls](https://redis.io/docs/latest/develop/clients/redis-py/transpipe/), if the individual operations are known to have the same command then that command SHOULD be used prepended by `MULTI ` or `PIPELINE `. Otherwise `db.operation.name` SHOULD be `MULTI` or `PIPELINE`. requirement_level: required sampling_relevant: true - ref: db.query.text sampling_relevant: true brief: > The full syntax of the Redis CLI command. examples: ["HMSET myhash field1 ? field2 ?"] requirement_level: recommended note: > 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/database/database-spans.md#sanitization-of-dbquerytext). The value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 ? field2 ?"` would be a suitable value for `db.query.text`. - ref: db.stored_procedure.name brief: > The name or sha1 digest of a Lua script in the database. note: > See [FCALL](https://redis.io/docs/latest/commands/fcall/) and [EVALSHA](https://redis.io/docs/latest/commands/evalsha/). requirement_level: recommended: If operation applies to a specific Lua script. - ref: network.peer.address brief: Peer address of the database node where the operation was performed. requirement_level: recommended note: > If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. - ref: network.peer.port requirement_level: recommended: if and only if `network.peer.address` is set. - ref: db.response.status_code brief: > The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. examples: ["ERR", "WRONGTYPE", "CLUSTERDOWN"] note: > All Redis error prefixes SHOULD be considered errors. - ref: db.operation.batch.size - ref: server.address sampling_relevant: true - ref: server.port sampling_relevant: true - id: span.db.mongodb.client type: span stability: development span_kind: client extends: trace.db.common.minimal brief: > Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: > `db.system.name` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.operation.name sampling_relevant: true brief: > The name of the [MongoDB command](https://www.mongodb.com/docs/manual/reference/command/) being executed. note: "" examples: ['findAndModify', 'getMore', 'insertMany', 'bulkWrite'] requirement_level: required - ref: db.collection.name sampling_relevant: true brief: The MongoDB collection being accessed within the database stated in `db.namespace`. note: > 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 are known to have the same collection name then that collection name SHOULD be used. requirement_level: required - ref: db.namespace sampling_relevant: true brief: The MongoDB database name. requirement_level: conditionally_required: If available. note: "" # overriding the base note - ref: db.response.status_code brief: > [MongoDB error code](https://www.mongodb.com/docs/manual/reference/error-codes/) represented as a string. note: > All MongoDB error codes SHOULD be considered errors. requirement_level: conditionally_required: If the operation failed and error code is available. examples: ["36", "11602"] - id: span.db.elasticsearch.client type: span stability: development span_kind: client extends: trace.db.common.minimal brief: > Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: | `db.system.name` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. attributes: - ref: http.request.method sampling_relevant: true requirement_level: required - ref: db.operation.name requirement_level: required note: > The `db.operation.name` SHOULD match the endpoint identifier provided in the request (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)). For batch operations, if the individual operations are known to have the same operation name then that operation name SHOULD be used prepended by `bulk `, otherwise `db.operation.name` SHOULD be `bulk`. examples: [ 'search', 'ml.close_job', 'cat.aliases' ] - ref: url.full sampling_relevant: true requirement_level: required examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] - ref: db.query.text sampling_relevant: true requirement_level: recommended: > Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ] - ref: db.collection.name sampling_relevant: true requirement_level: recommended brief: The index or data stream against which the query is executed. note: > The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set. examples: [ 'my_index', 'index1, index2' ] - ref: db.namespace sampling_relevant: true note: > When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. brief: The name of the Elasticsearch cluster which the client connects to. requirement_level: recommended - ref: elasticsearch.node.name note: > When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. requirement_level: recommended - ref: db.operation.parameter stability: development brief: > A dynamic value in the url path. note: > Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.operation.parameter.`, where `` is the path parameter name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path parameter values to their names. examples: [ 'db.operation.parameter.index="test-index"', 'db.operation.parameter="123"', ] requirement_level: conditionally_required: when the url has path parameters - ref: db.response.status_code brief: > The HTTP response code returned by the Elasticsearch cluster. examples: ["200", "201", "429"] note: > HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. requirement_level: conditionally_required: If response was received. - id: span.db.sql.client type: span span_kind: client stability: release_candidate extends: trace.db.common.query brief: > The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. note: | The following database systems (defined in the [`db.system.name`](/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: - `actian.ingres` - `cockroachdb` - `derby` - `firebirdsql` - `h2database` - `hsqldb` - `ibm.db2` - `mariadb` - `microsoft.sql_server` - `mysql` - `oracle.db` - `other_sql` - `postgresql` - `sap.maxdb` - `sqlite` - `trino` Many other database systems support SQL and can be accessed via generic database driver such as JDBC or ODBC. Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic conventions. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.namespace brief: > The database associated with the connection, fully qualified within the server address and port. requirement_level: conditionally_required: If available without an additional network call. note: | If a database system has multiple namespace components (e.g. schema name and database name), 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. A connection's currently associated database may change during its lifetime, e.g. from executing `USE `. If instrumentation is unable to capture the connection's currently associated database on each query without triggering an additional query to be executed (e.g. `SELECT DATABASE()`), then it is RECOMMENDED to fallback and use the database provided when the connection was established. Instrumentation SHOULD document if `db.namespace` reflects the database provided when the connection was established. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - ref: db.response.status_code brief: > Database response code recorded as a string. note: | SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database return code which is adopted by some database systems like PostgreSQL. See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) for the details. Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific error codes. Database SQL drivers usually provide access to both properties. For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) class reports them with `getSQLState()` and `getErrorCode()` methods. Instrumentations SHOULD populate the `db.response.status_code` with the the most specific code available to them. Here's a non-exhaustive list of databases that report vendor-specific codes with granularity higher than SQLSTATE (or don't report SQLSTATE at all): - [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). - [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) - [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) - [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) - [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) - [SQLite result codes](https://www.sqlite.org/rescode.html) These systems SHOULD set the `db.response.status_code` to a known vendor-specific error code. If only SQLSTATE is available, it SHOULD be used. When multiple error codes are available and specificity is unclear, instrumentation SHOULD set the `db.response.status_code` to the concatenated string of all codes with '/' used as a separator. For example, generic DB instrumentation that detected an error and has SQLSTATE `"42000"` and vendor-specific `1071` should set `db.response.status_code` to `"42000/1071"`." examples: ["ORA-17027", "1052", "2201B"] requirement_level: conditionally_required: If response has ended with warning or an error. - ref: db.stored_procedure.name requirement_level: recommended: If operation applies to a specific stored procedure. - ref: db.operation.name requirement_level: recommended: If the operation is executed via a higher-level API that does not support multiple operation names. note: | The operation name SHOULD NOT be extracted from `db.query.text`. examples: ["EXECUTE", "INSERT"] - ref: db.collection.name requirement_level: recommended: If the operation is executed via a higher-level API that does not support multiple collection names. note: | The collection name SHOULD NOT be extracted from `db.query.text`. - ref: db.response.returned_rows requirement_level: opt_in # experimental attributes must be opt-in stable spans # TODO (trask) make this recommended once it is stable - id: span.azure.cosmosdb.client type: span stability: development span_kind: client extends: trace.db.common.minimal brief: > Cosmos DB instrumentations include call-level spans that represent logical database calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). note: | Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). Semantic conventions described in this document apply to the call-level spans only. `db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: azure.client.id - ref: user_agent.original brief: 'Full user-agent string is generated by Cosmos DB SDK' note: > The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". examples: ['cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|'] - ref: azure.cosmosdb.connection.mode requirement_level: conditionally_required: if not `gateway` (the default value is assumed to be `gateway`). - ref: db.collection.name brief: > Cosmos DB container name. note: > It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. requirement_level: conditionally_required: if available sampling_relevant: true - ref: azure.cosmosdb.request.body.size - ref: db.response.status_code brief: > Cosmos DB status code. examples: ["200", "201"] note: > Response codes in the 4xx and 5xx range SHOULD be considered errors. requirement_level: conditionally_required: if response was received - ref: db.response.returned_rows brief: > Cosmos DB row count in result set. examples: [10, 20] requirement_level: conditionally_required: if response was received and returned any rows - ref: azure.cosmosdb.response.sub_status_code requirement_level: conditionally_required: when response was received and contained sub-code. - ref: azure.cosmosdb.operation.request_charge requirement_level: conditionally_required: when available - ref: db.namespace sampling_relevant: true requirement_level: conditionally_required: If available. note: "" # overriding the base note - ref: az.namespace note: > When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. examples: ["Microsoft.DocumentDB"] - ref: db.operation.name requirement_level: required note: | The `db.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used. Batch operations: - `execute_batch` Bulk operations: - `execute_bulk` SHOULD be used on spans reported for methods like [`executeBulkOperations`](https://javadoc.io/doc/com.azure/azure-cosmos/latest/com/azure/cosmos/CosmosAsyncContainer.html#executeBulkOperations)). which represents a bulk execution of multiple operations. - `bulk_{operation name}` (`bulk_create_item`, `bulk_upsert_item`, etc) SHOULD be used on spans describing individual operations (when they are reported) within the bulk. This pattern SHOULD be used when instrumentation creates span per each operation, but operations are buffered and then performed in bulk. For example, this applies when [`AllowBulkExecution`](https://learn.microsoft.com/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.allowbulkexecution) property is configured on the `Microsoft.Azure.Cosmos` client. Change feed operations: - `query_change_feed` Conflicts operations: - `delete_conflict` - `query_conflicts` - `read_all_conflicts` - `read_conflict` Container operations: - `create_container` - `create_container_if_not_exists` - `delete_container` - `query_containers` - `read_all_containers` - `read_container` - `read_container_throughput` - `replace_container` - `replace_container_throughput` Database operations: - `create_database` - `create_database_if_not_exists` - `delete_database` - `query_databases` - `read_all_databases` - `read_database` - `read_database_throughput` - `replace_database_throughput` Encryption key operations: - `create_client_encryption_key` - `query_client_encryption_keys` - `read_all_client_encryption_keys` - `read_client_encryption_key` - `replace_client_encryption_key` Item operations: - `create_item` - `delete_all_items_by_partition_key` - `delete_item` - `patch_item` - `query_items` - `read_all_items` - `read_all_items_of_logical_partition` - `read_many_items` - `read_item` - `replace_item` - `upsert_item` Permission operations: - `create_permission` - `delete_permission` - `query_permissions` - `read_all_permissions` - `read_permission` - `replace_permission` - `upsert_permission` Stored procedure operations: - `create_stored_procedure` - `delete_stored_procedure` - `execute_stored_procedure` - `query_stored_procedures` - `read_all_stored_procedures` - `read_stored_procedure` - `replace_stored_procedure` Trigger operations: - `create_trigger` - `delete_trigger` - `query_triggers` - `read_all_triggers` - `read_trigger` - `replace_trigger` User operations: - `create_user` - `delete_user` - `query_users` - `read_all_users` - `read_user` - `replace_user` - `upsert_user` User-defined function operations: - `create_user_defined_function` - `delete_user_defined_function` - `query_user_defined_functions` - `read_all_user_defined_functions` - `read_user_defined_function` If none of them applies, it's RECOMMENDED to use language-agnostic representation of client method name in snake_case. Instrumentations SHOULD document additional values when introducing new operations. examples: ['create_item', 'query_items', 'read_item'] - ref: db.stored_procedure.name requirement_level: recommended: If operation applies to a specific stored procedure. - ref: server.port requirement_level: conditionally_required: If not default (443). - ref: azure.cosmosdb.consistency.level requirement_level: conditionally_required: If available. - ref: azure.cosmosdb.operation.contacted_regions requirement_level: conditionally_required: If available. - ref: db.query.text # TODO: this might not be the right attribute to use here - https://github.com/open-telemetry/semantic-conventions/issues/2213 - ref: db.query.parameter requirement_level: opt_in - id: span.db.oracledb.client type: span stability: development extends: span.db.sql.client span_kind: client brief: > Spans representing calls to a Oracle SQL Database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). note: | `db.system.name` MUST be set to `"oracle.db"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true brief: > The database associated with the connection, qualified by the instance name, database name and service name. note: | `db.namespace` SHOULD be set to the combination of instance name, database name and service name following the `{service_name}|{database_name}|{instance_name}` pattern. Any missing components (and their associated separators) SHOULD be omitted. For CDB architecture, database name would be pdb name. For Non-CDB, it would be `DB_NAME` parameter. examples: ["ORCL1\\|PDB1\\|db_high.adb.oraclecloud.com", "ORCL1\\|DB1\\|db_low.adb.oraclecloud.com", "ORCL1\\|DB1\\|order-processing-service"] - ref: db.response.status_code brief: > [Oracle Database error number](https://docs.oracle.com/en/error-help/db/) recorded as a string. note: > Oracle Database error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All Oracle Database error codes SHOULD be considered errors. examples: ["ORA-02813", "ORA-02613"] - ref: db.query.text sampling_relevant: true brief: > The database query being executed. requirement_level: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, see [`db.query.parameter.`](../attributes-registry/db.md)). note: > For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text 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. examples: ["SELECT * FROM wuser_table where username = :mykey"]