semantic-conventions/model/database/spans.yaml

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 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.<key>`](/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.<key>`](/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.

  - id: span.db.client
    type: span
    stability: release_candidate
    brief: This span describes database client call.
    note: |
      It SHOULD cover the duration of the corresponding 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.

      **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

  - 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 <database>`.

          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 <schema>`.
          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 <database>`.

          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 <database>`.

          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:
          conditionally_required: If readily available.
      - 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 <index>`.

          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`.          
        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 represents Lua script execution.
      - 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:
          conditionally_required: If readily available.
      - 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.<key>`, where `<key>` 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 <database>`.

          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 represents a stored procedure execution.
  - id: span.azure.cosmosdb.client
    type: span
    stability: development
    span_kind: client
    extends: trace.db.common.query_and_collection
    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<br>
          `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br>
          `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br>
          `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br>
          `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br>
          `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br>
          `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br>
          `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
      - 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
        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 represents a stored procedure execution.
      - 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.
  - 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.<key>`](../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"]