diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 1157143402..eac8fa6dc9 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -16,9 +16,9 @@ This group defines the attributes used to describe telemetry in the context of d | `db.client.connection.pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | ![Development](https://img.shields.io/badge/-development-blue) | | `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Development](https://img.shields.io/badge/-development-blue) | | `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.command.name` | string | The name of the command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [3] | `customers`; `test.users` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.operation.batch.size` | int | The number of queries included in a batch operation. [4] | `2`; `3`; `4` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `db.operation.parameter.` | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `db.query.summary` | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `db.query.text` | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | @@ -35,23 +35,23 @@ when the database system supports cross-table queries in non-batch operations. For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -**[2] `db.namespace`:** 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. -Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - -**[3] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. - -**[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[2] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -The operation name SHOULD NOT be extracted from `db.query.text`, +The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. -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` or some other database +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +**[3] `db.namespace`:** 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. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + +**[4] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. + **[5] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. @@ -156,7 +156,8 @@ Describes deprecated database attributes. | `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | | `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | | `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | +| `db.operation` | string | Deprecated, use `db.command.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.command.name`. | +| `db.operation.name` | string | Deprecated, use `db.command.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Development](https://img.shields.io/badge/-development-blue) | | `db.query.parameter.` | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. | `someval`; `55` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.parameter`. | | `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | | `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 697ba36d19..3a56dc26f7 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -33,8 +33,8 @@ The following table outlines the span attributes applicable to Cassandra. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the Cassandra table that the operation is acting upon. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The keyspace associated with the session. [3] | `mykeyspace` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The keyspace associated with the session. [5] | `mykeyspace` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. [6] | `102`; `40020` | `Conditionally Required` [7] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [8] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Conditionally Required` [10] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -61,22 +61,22 @@ then that collection name SHOULD be used. **[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. -**[3] `db.namespace`:** 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. -Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - -**[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[3] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -The operation name SHOULD NOT be extracted from `db.query.text`, +The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. -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` or some other database +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. +**[4] `db.command.name`:** If readily available and if there is a single command name that describes the database operation. + +**[5] `db.namespace`:** 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. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[6] `db.response.status_code`:** All Cassandra protocol error codes SHOULD be considered errors. @@ -115,8 +115,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`db.query.summary`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) * [`server.address`](/docs/attributes-registry/server.md) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 5018e21560..44e12a6181 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -47,8 +47,8 @@ The following table outlines the span attributes applicable to Cosmos DB. | [`azure.cosmosdb.operation.request_charge`](/docs/attributes-registry/azure.md) | double | The number of request units consumed by the operation. | `46.18`; `1.0` | `Conditionally Required` when available | ![Development](https://img.shields.io/badge/-development-blue) | | [`azure.cosmosdb.response.sub_status_code`](/docs/attributes-registry/azure.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Development](https://img.shields.io/badge/-development-blue) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [3] | `public.users`; `customers` | `Conditionally Required` if available | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [4] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` if response was received and returned any rows | ![Development](https://img.shields.io/badge/-development-blue) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [6] | `200`; `201` | `Conditionally Required` if response was received | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -69,7 +69,7 @@ The following table outlines the span attributes applicable to Cosmos DB. **[3] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[4] `db.operation.name`:** The `db.operation.name` has the following list of well-known values. +**[4] `db.command.name`:** The `db.command.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used. Batch operations: @@ -193,7 +193,7 @@ If none of them applies, it's RECOMMENDED to use language-agnostic representatio client method name in snake_case. Instrumentations SHOULD document additional values when introducing new operations. -**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. +**[5] `db.command.name`:** If readily available and if there is a single command name that describes the database operation. **[6] `db.response.status_code`:** Response codes in the 4xx and 5xx range SHOULD be considered errors. @@ -232,8 +232,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`db.query.summary`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) * [`server.address`](/docs/attributes-registry/server.md) @@ -344,8 +344,8 @@ Explaining bucket configuration: | [`azure.cosmosdb.consistency.level`](/docs/attributes-registry/azure.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. | ![Development](https://img.shields.io/badge/-development-blue) | | [`azure.cosmosdb.response.sub_status_code`](/docs/attributes-registry/azure.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Development](https://img.shields.io/badge/-development-blue) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -354,15 +354,15 @@ Explaining bucket configuration: **[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[2] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -The operation name SHOULD NOT be extracted from `db.query.text`, +The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. -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` or some other database +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 6fd4a11171..ac7731ec8e 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -32,15 +32,15 @@ The following table outlines the span attributes applicable to CouchDB. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB recorded as a string. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1] `db.operation.name`:** 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). +**[1] `db.command.name`:** In **CouchDB**, `db.command.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.command.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). **[2] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. @@ -61,8 +61,8 @@ Instrumentations SHOULD document how `error.type` is populated. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`server.address`](/docs/attributes-registry/server.md) * [`server.port`](/docs/attributes-registry/server.md) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index f48306e793..b094e55ee1 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -83,8 +83,8 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. |---|---|---|---|---|---| | [`db.system.name`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `softwareag.adabas`; `actian.ingres` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [6] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -107,22 +107,22 @@ collection name then that collection name SHOULD be used. **[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. -**[4] `db.namespace`:** 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. -Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - -**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[4] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -The operation name SHOULD NOT be extracted from `db.query.text`, +The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. -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` or some other database +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -**[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. +**[5] `db.command.name`:** If readily available and if there is a single command name that describes the database operation. + +**[6] `db.namespace`:** 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. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. @@ -250,8 +250,8 @@ Explaining bucket configuration: |---|---|---|---|---|---| | [`db.system.name`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `softwareag.adabas`; `actian.ingres` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [6] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -274,22 +274,22 @@ collection name then that collection name SHOULD be used. **[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. -**[4] `db.namespace`:** 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. -Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - -**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[4] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -The operation name SHOULD NOT be extracted from `db.query.text`, +The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. -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` or some other database +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -**[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. +**[5] `db.command.name`:** If readily available and if there is a single command name that describes the database operation. + +**[6] `db.namespace`:** 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. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index fb0ef94083..a8fe872241 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -107,8 +107,8 @@ These attributes are commonly used across different database systems. |---|---|---|---|---|---| | [`db.system.name`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `softwareag.adabas`; `actian.ingres` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [6] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -134,22 +134,22 @@ collection name then that collection name SHOULD be used. **[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. -**[4] `db.namespace`:** 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. -Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - -**[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[4] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -The operation name SHOULD NOT be extracted from `db.query.text`, +The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. -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` or some other database +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -**[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. +**[5] `db.command.name`:** If readily available and if there is a single command name that describes the database operation. + +**[6] `db.namespace`:** 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. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. @@ -190,8 +190,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`db.query.summary`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) * [`db.system.name`](/docs/attributes-registry/db.md) diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 28d02f2f10..d1df44d3a0 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -35,7 +35,7 @@ The following table outlines the span attributes applicable to Elasticsearch. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.full`](/docs/attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [3] | `https://localhost:9200/index/_search?q=user.id:kimchy` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A dynamic value in the url path. [4] | `db.operation.parameter.index="test-index"`; `db.operation.parameter="123"` | `Conditionally Required` when the url has path parameters | ![Development](https://img.shields.io/badge/-development-blue) | @@ -49,8 +49,8 @@ The following table outlines the span attributes applicable to Elasticsearch. | [`elasticsearch.node.name`](/docs/attributes-registry/elasticsearch.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. [14] | `instance-0000000001` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1] `db.operation.name`:** 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`. +**[1] `db.command.name`:** The `db.command.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 command name then that command name SHOULD be used prepended by `bulk `, otherwise `db.command.name` SHOULD be `bulk`. **[2] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -123,8 +123,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) * [`http.request.method`](/docs/attributes-registry/http.md) * [`server.address`](/docs/attributes-registry/server.md) diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 14682bee0f..389e224a9e 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -33,8 +33,8 @@ The following table outlines the span attributes applicable to HBase. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [3] | `mynamespace` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as a string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -43,16 +43,16 @@ The following table outlines the span attributes applicable to HBase. **[1] `db.collection.name`:** 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. -**[2] `db.namespace`:** 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. -Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - -**[3] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application +**[2] `db.command.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For batch operations, if the individual operations 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`. +For batch operations, if the individual operations are known to have the same command name +then that command name SHOULD be used prepended by `BATCH `, +otherwise `db.command.name` SHOULD be `BATCH`. + +**[3] `db.namespace`:** 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. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. @@ -73,8 +73,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`server.address`](/docs/attributes-registry/server.md) * [`server.port`](/docs/attributes-registry/server.md) diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 7b07d25e45..3b7e97186c 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -37,8 +37,8 @@ The following table outlines the span attributes applicable to MongoDB. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.namespace`. [1] | `public.users`; `customers` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The name of the [MongoDB command](https://www.mongodb.com/docs/manual/reference/command/) being executed. | `findAndModify`; `getMore`; `insertMany`; `bulkWrite` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The MongoDB database name. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the [MongoDB command](https://www.mongodb.com/docs/manual/reference/command/) being executed. | `findAndModify`; `getMore`; `insertMany`; `bulkWrite` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MongoDB error code](https://www.mongodb.com/docs/manual/reference/error-codes/) represented as a string. [2] | `36`; `11602` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -68,8 +68,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/attributes-registry/db.md) +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`server.address`](/docs/attributes-registry/server.md) * [`server.port`](/docs/attributes-registry/server.md) diff --git a/docs/database/redis.md b/docs/database/redis.md index e126351f33..0ad443c48a 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -27,8 +27,8 @@ looking confusing. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The [database index] associated with the connection, represented as a string. [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The Redis command name. [2] | `HMSET`; `GET`; `SET` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.command.name`](/docs/attributes-registry/db.md) | string | The Redis command name. [1] | `HMSET`; `GET`; `SET` | `Conditionally Required` [2] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The [database index] associated with the connection, represented as a string. [3] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. [4] | `ERR`; `WRONGTYPE`; `CLUSTERDOWN` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -39,7 +39,12 @@ looking confusing. | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -**[1] `db.namespace`:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. +**[1] `db.command.name`:** 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 name then that command name SHOULD be used prepended by `MULTI ` or `PIPELINE `. Otherwise `db.command.name` SHOULD be `MULTI` or `PIPELINE`. + +**[2] `db.command.name`:** If readily available and if there is a single command name that describes the database operation. + +**[3] `db.namespace`:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. If instrumentation is unable to capture the connection's currently associated database index on each query without triggering an additional query to be executed, @@ -47,11 +52,6 @@ then it is RECOMMENDED to fallback and use the database index provided when the Instrumentation SHOULD document if `db.namespace` reflects the database index provided when the connection was established. -**[2] `db.operation.name`:** 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`. - -**[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. - **[4] `db.response.status_code`:** All Redis error prefixes SHOULD be considered errors. **[5] `db.response.status_code`:** If the operation failed and status code is available. @@ -82,8 +82,8 @@ If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): +* [`db.command.name`](/docs/attributes-registry/db.md) * [`db.namespace`](/docs/attributes-registry/db.md) -* [`db.operation.name`](/docs/attributes-registry/db.md) * [`db.query.text`](/docs/attributes-registry/db.md) * [`server.address`](/docs/attributes-registry/server.md) * [`server.port`](/docs/attributes-registry/server.md) diff --git a/model/database/common.yaml b/model/database/common.yaml index c8ed755bd9..ac1f7dd0f8 100644 --- a/model/database/common.yaml +++ b/model/database/common.yaml @@ -35,7 +35,7 @@ groups: # - ref: db.system.name # requirement_level: # conditionally_required: if available - - ref: db.operation.name + - ref: db.command.name requirement_level: conditionally_required: If readily available. - ref: db.collection.name @@ -68,13 +68,13 @@ groups: extends: attributes.db.client.with_query type: attribute_group brief: This group defines the attributes describing database operations that - have operation name, collection name and query. + have command name, collection name and query. attributes: - - ref: db.operation.name + - ref: db.command.name requirement_level: conditionally_required: > - If readily available and if there is a single operation name that describes the - database call. + If readily available and if there is a single command name that describes the + database operation. - ref: db.collection.name requirement_level: conditionally_required: > diff --git a/model/database/deprecated/metrics-deprecated.yaml b/model/database/deprecated/metrics-deprecated.yaml index 93273a4c59..fd707d53b8 100644 --- a/model/database/deprecated/metrics-deprecated.yaml +++ b/model/database/deprecated/metrics-deprecated.yaml @@ -118,12 +118,12 @@ groups: unit: "{request_unit}" stability: development attributes: - - ref: db.operation.name + - ref: db.command.name requirement_level: conditionally_required: > - If readily available and if there is a single operation name that describes the - database call. The operation name MAY be parsed from the query text, - in which case it SHOULD be the single operation name found in the query. + If readily available and if there is a single command name that describes the + database call. The command name MAY be parsed from the query text, + in which case it SHOULD be the single command name found in the query. - ref: db.collection.name brief: Cosmos DB container name. requirement_level: diff --git a/model/database/deprecated/registry-deprecated.yaml b/model/database/deprecated/registry-deprecated.yaml index 741dad9ef9..24c5a03bbe 100644 --- a/model/database/deprecated/registry-deprecated.yaml +++ b/model/database/deprecated/registry-deprecated.yaml @@ -20,9 +20,9 @@ groups: examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver'] - id: db.operation type: string - brief: 'Deprecated, use `db.operation.name` instead.' + brief: 'Deprecated, use `db.command.name` instead.' stability: development - deprecated: "Replaced by `db.operation.name`." + deprecated: "Replaced by `db.command.name`." examples: ['findAndModify', 'HMSET', 'SELECT'] - id: db.user type: string @@ -80,6 +80,11 @@ groups: brief: 'Deprecated, use `db.namespace` instead.' deprecated: "Replaced by `db.namespace`." examples: [ 'customers', 'main' ] + - id: db.operation.name + type: string + stability: development + brief: 'Deprecated, use `db.command.name` instead.' + examples: ["findAndModify", "HMSET", "SELECT"] - id: db.mssql.instance_name type: string stability: development diff --git a/model/database/registry.yaml b/model/database/registry.yaml index dc4507bc5c..7695776f36 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -35,21 +35,21 @@ groups: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ["customers", "test.users"] - - id: db.operation.name + - id: db.command.name type: string stability: release_candidate brief: > - The name of the operation or command being executed. + The name of the command being executed. note: | It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - The operation name SHOULD NOT be extracted from `db.query.text`, + The command name SHOULD NOT be extracted from `db.query.text` when the database system supports cross-table queries in non-batch operations. - 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` or some other database + For batch operations, if the individual operations are known to have the same command name + then that command name SHOULD be used prepended by `BATCH `, + otherwise `db.command.name` SHOULD be `BATCH` or some other database system specific term if more applicable. examples: ["findAndModify", "HMSET", "SELECT"] - id: db.query.text diff --git a/model/database/spans.yaml b/model/database/spans.yaml index ff6d99db16..b29b12fe60 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -7,12 +7,12 @@ groups: # 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 + - ref: db.command.name sampling_relevant: true requirement_level: conditionally_required: > - If readily available and if there is a single operation name that describes the - database call. + If readily available and if there is a single command name that describes the + database operation. - ref: db.operation.batch.size - ref: server.address sampling_relevant: true @@ -53,7 +53,7 @@ groups: attributes: - ref: db.collection.name sampling_relevant: true - - ref: db.operation.name + - ref: db.command.name sampling_relevant: true - ref: db.operation.batch.size - ref: server.address @@ -319,14 +319,14 @@ groups: 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 + - ref: db.command.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`. + For batch operations, if the individual operations are known to have the same command name + then that command name SHOULD be used prepended by `BATCH `, + otherwise `db.command.name` SHOULD be `BATCH`. requirement_level: conditionally_required: If readily available. - ref: db.response.status_code @@ -343,15 +343,15 @@ groups: brief: > Attributes for CouchDB attributes: - - ref: db.operation.name + - ref: db.command.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 + + In **CouchDB**, `db.command.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 + For example, when retrieving a document, `db.command.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: @@ -393,7 +393,7 @@ groups: Instrumentation SHOULD document if `db.namespace` reflects the database index provided when the connection was established. examples: ["0", "1", "15"] - - ref: db.operation.name + - ref: db.command.name brief: > The Redis command name. examples: ["HMSET", "GET", "SET"] @@ -402,9 +402,9 @@ groups: 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`. + if the individual operations are known to have the same command name then that + command name SHOULD be used prepended by `MULTI ` or `PIPELINE `. + Otherwise `db.command.name` SHOULD be `MULTI` or `PIPELINE`. sampling_relevant: true - ref: db.query.text sampling_relevant: true @@ -455,7 +455,7 @@ groups: brief: > Attributes for MongoDB attributes: - - ref: db.operation.name + - ref: db.command.name sampling_relevant: true brief: > The name of the [MongoDB command](https://www.mongodb.com/docs/manual/reference/command/) being executed. @@ -499,15 +499,15 @@ groups: - ref: http.request.method sampling_relevant: true requirement_level: required - - ref: db.operation.name + - ref: db.command.name requirement_level: required note: > - The `db.operation.name` SHOULD match the endpoint identifier provided in the request + The `db.command.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`. + For batch operations, if the individual operations are known to have the same command name + then that command name SHOULD be used prepended by `bulk `, + otherwise `db.command.name` SHOULD be `bulk`. examples: [ 'search', 'ml.close_job', 'cat.aliases' ] - ref: url.full sampling_relevant: true @@ -702,9 +702,9 @@ groups: 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 + - ref: db.command.name note: | - The `db.operation.name` has the following list of well-known values. + The `db.command.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used. Batch operations: