semantic-conventions/model/trace/database.yaml

groups:
  - id: trace.db.common
    extends: attributes.db.client
    type: attribute_group
    brief: This group defines the attributes used to perform database client calls.
    attributes:
      - ref: db.query.text
        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.

            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)).            
        note:
          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.
      - ref: db.query.parameter
        requirement_level: opt_in

  - id: db.tech_specific.network.attributes
    type: attribute_group
    brief: This group documents attributes that describe database call along with network information.
    extends: trace.db.common
    attributes:
      - ref: network.peer.address
        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.          
        tag: tech-specific
      - ref: network.peer.port
        tag: tech-specific

  - id: db
    type: span
    brief: This span defines the attributes used to perform database client calls.
    span_kind: client
    extends: trace.db.common

  - id: db.mssql
    type: span
    extends: db.sql
    brief: >
      Attributes for Microsoft SQL Server      
    attributes:
      - ref: db.namespace
        brief: The name of the database, fully qualified within the server address and port.
        note:
          When connecting to a default instance, `db.namespace` SHOULD be set to the name of
          the database. When connecting 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.

          For commands that switch the database, this SHOULD be set to the target database (even if the command fails).
        examples: ["instance1.products", "customers"]
        tag: tech-specific

  - id: db.cassandra
    type: span
    extends: db.tech_specific.network.attributes
    brief: >
      Attributes for Cassandra      
    attributes:
      - ref: db.namespace
        brief: The Cassandra keyspace name.
        note: For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails).
        examples: ["mykeyspace"]
        tag: tech-specific
      - ref: db.cassandra.page_size
        tag: tech-specific
      - ref: db.cassandra.consistency_level
        tag: tech-specific
      - ref: db.collection.name
        brief: The name of the Cassandra table that the operation is acting upon.
        tag: tech-specific
      - ref: db.cassandra.idempotence
        tag: tech-specific
      - ref: db.cassandra.speculative_execution_count
        tag: tech-specific
      - ref: db.cassandra.coordinator.id
        tag: tech-specific
      - ref: db.cassandra.coordinator.dc
        tag: tech-specific

  - id: db.hbase
    type: span
    extends: trace.db.common
    brief: >
      Attributes for HBase      
    attributes:
      - ref: db.namespace
        brief: The HBase namespace.
        requirement_level:
          conditionally_required: If applicable.
        note: >
          When performing table-related operations, the instrumentations SHOULD extract the namespace from the table name according to
          the [HBase table naming conventions](https://hbase.apache.org/book.html#namespace_creation). If namespace is not provided,
          instrumentation SHOULD set `db.namespace` value to `default`.          
        examples: ['mynamespace']
        tag: tech-specific
      - ref: db.collection.name
        brief: The HBase table name.
        requirement_level:
          conditionally_required: If applicable.
        note: >
          If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name.          
        examples: ['mytable', 'ns:table']
        tag: tech-specific

  - id: db.couchdb
    type: span
    extends: trace.db.common
    brief: >
      Attributes for CouchDB      
    attributes:
      - ref: db.operation.name
        tag: tech-specific
        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).          

  - id: db.redis
    type: span
    extends: db.tech_specific.network.attributes
    brief: >
      Attributes for Redis      
    attributes:
      - ref: db.namespace
        brief: >
          The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select).          
        requirement_level:
          conditionally_required: If and only if it can be captured reliably.
        note: >
          The database index for current connection can be changed by the application dynamically. Instrumentations MAY use
          the initial database index provided in the connection string and keep track of the currently selected
          database to capture the `db.namespace`.

          Instrumentations SHOULD NOT set this attribute if capturing it would require additional network calls to Redis.

          For commands that switch the database, this SHOULD be set to the target database (even if the command fails).          
        examples: ["0", "1", "15"]
        tag: tech-specific
      - ref: db.query.text
        tag: tech-specific
        brief: >
          The full syntax of the Redis CLI command.          
        examples: ["HMSET myhash field1 'Hello' field2 'World'"]
        note: >
          For **Redis**, 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/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`.          

  - id: db.mongodb
    type: span
    extends: trace.db.common
    brief: >
      Attributes for MongoDB      
    attributes:
      - ref: db.operation.name
        brief: >
          The name of the command being executed.          
        note: >
          See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/).          
        examples: ['findAndModify', 'getMore', 'update']
        tag: tech-specific
      - ref: db.collection.name
        brief:
          The MongoDB collection being accessed within the database stated in `db.namespace`.
        requirement_level: required
        tag: tech-specific
      - ref: db.namespace
        brief: The MongoDB database name.
        note: |
          <!-- TODO: overriding the base note, workaround for https://github.com/open-telemetry/build-tools/issues/299 -->          
        tag: tech-specific

  - id: db.elasticsearch
    type: span
    extends: db.tech_specific.network.attributes
    brief: >
      Attributes for Elasticsearch      
    attributes:
      - ref: http.request.method
        requirement_level: required
        tag: tech-specific
      - ref: db.operation.name
        requirement_level: required
        note: This SHOULD be the endpoint identifier for the request.
        examples: [ 'search', 'ml.close_job', 'cat.aliases' ]
        tag: tech-specific
      - ref: url.full
        requirement_level: required
        examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ]
        tag: tech-specific
      - ref: db.query.text
        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\"}}}"' ]
        tag: tech-specific
      - ref: server.address
        tag: tech-specific
      - ref: server.port
        tag: tech-specific
      - ref: db.elasticsearch.cluster.name
        requirement_level:
          recommended: >
            When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.            
        tag: tech-specific
      - ref: db.elasticsearch.node.name
        requirement_level:
          recommended: >
            When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.            
        tag: tech-specific
      - ref: db.elasticsearch.path_parts
        requirement_level:
          conditionally_required: when the url has dynamic values
        tag: tech-specific

  - id: db.sql
    type: span
    extends: trace.db.common
    brief: >
      Attributes for SQL databases      
    attributes:
      - ref: db.operation.name
        note: >
          This SHOULD be the SQL command such as `SELECT`, `INSERT`, `UPDATE`, `CREATE`, `DROP`.

          In the case of `EXEC`, this SHOULD be the stored procedure name that is being executed.          
        examples: ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'mystoredproc']
        tag: tech-specific
      - ref: db.collection.name
        brief: The name of the SQL table that the operation is acting upon.
        examples: ['users', 'dbo.products']
        tag: tech-specific
      - ref: db.namespace
        note: |
          If a database system has multiple namespace components, they SHOULD be concatenated
          (potentially using database system specific conventions) from most general to most
          specific namespace component, and more specific namespaces SHOULD NOT be captured without
          the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.

          Unless specified by the system-specific semantic convention, the `db.namespace` attribute matches
          the name of the database being accessed.

          The database name can usually be obtained with database driver API such as
          [JDBC `Connection.getCatalog()`](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#getCatalog--)
          or [.NET `SqlConnection.Database`](https://learn.microsoft.com/dotnet/api/system.data.sqlclient.sqlconnection.database).

          Some database drivers don't detect when the current database is changed (for example, with SQL `USE database` statement).
          Instrumentations that parse SQL statements MAY use the database name provided
          in the connection string and keep track of the currently selected database name.

          For commands that switch the database, this SHOULD be set to the target database (even if the command fails).

          If instrumentation cannot reliably determine the current database name, it SHOULD NOT set `db.namespace`.          
        tag: tech-specific
  - id: db.cosmosdb
    type: span
    extends: trace.db.common
    prefix: db.cosmosdb
    brief: >
      Attributes for Cosmos DB.      
    attributes:
      - ref: db.cosmosdb.client_id
        tag: tech-specific
      - ref: db.cosmosdb.operation_type
        requirement_level:
          conditionally_required: when performing one of the operations in this list
        tag: tech-specific
      - 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\|']
        tag: tech-specific
      - ref: db.cosmosdb.connection_mode
        requirement_level:
          conditionally_required: if not `direct` (or pick gw as default)
        tag: tech-specific
      - ref: db.collection.name
        brief: >
          Cosmos DB container name.          
        requirement_level:
          conditionally_required: if available
        tag: tech-specific
      - ref: db.cosmosdb.request_content_length
        tag: tech-specific
      - ref: db.cosmosdb.status_code
        requirement_level:
          conditionally_required: if response was received
        tag: tech-specific
      - ref: db.cosmosdb.sub_status_code
        requirement_level:
          conditionally_required: when response was received and contained sub-code.
        tag: tech-specific
      - ref: db.cosmosdb.request_charge
        requirement_level:
          conditionally_required: when available
        tag: tech-specific