open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
semantic-conventions/model/database/spans.yaml

984 lines
47 KiB
YAML
Raw Blame History

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 'Hello' field2 'World'"]
requirement_level:
recommended: >
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).
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/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` 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"]
Reference in New Issue View Git Blame Copy Permalink