From 213d70c3b417c714f9799eccc0853c67a62844cc Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 07:48:43 -0700 Subject: [PATCH 1/8] yaml --- docs/database/database-spans.md | 12 ++++++++++ model/metrics/database-metrics.yaml | 2 ++ model/registry/db.yaml | 35 ++++++++++++++++++++++++++++- 3 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 0f74b9231b..e3616f3c98 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -71,6 +71,18 @@ The `{target}` SHOULD adhere to one of the - `server.address:server.port` - `db.system` +## Batch operations + +### Homogeneous batches + +Homogeneous batches are batches of two or more operations where the individual operations are known to all have the +same `db.query.text`. + +### Heterogeneous batches + +Heterogeneous batches are batches of two or more operations where individual operations are not known to all have the +same `db.query.text`. + ## Common attributes These attributes will usually be the same for all operations performed over the same database connection. diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 0b0823406c..c537bd8237 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -3,6 +3,8 @@ groups: type: metric metric_name: db.client.operation.duration brief: "Duration of database client operations." + note: > + Batch operations SHOULD be recorded as a single operation. instrument: histogram unit: "s" stability: experimental diff --git a/model/registry/db.yaml b/model/registry/db.yaml index 48bb854ebe..e41b3b5102 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -13,7 +13,15 @@ groups: If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. - It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query + and it SHOULD match the value provided in the query text including any schema and database name prefix. + + For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, + that collection name SHOULD be used. + For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, + that collection name SHOULD be used. + For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, + `db.collection.name` SHOULD NOT be captured. examples: ['public.users', 'customers'] - id: namespace type: string @@ -36,6 +44,16 @@ groups: stability: experimental brief: > The name of the operation or command being executed. + + For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), + individual operations will all have the same operation name and so that operation name SHOULD be used, + prepended by `BATCH `. + For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) + where individual operations are known to all have the same operation name, that operation name SHOULD be used, + prepended by `BATCH `. + For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) + where individual operations are not known to all have the same operation name, + `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. note: > It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ['findAndModify', 'HMSET', 'SELECT'] @@ -44,6 +62,13 @@ groups: stability: experimental brief: > The database query being executed. + note: > + For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), + individual operations will all have the same query text and so that query text SHOULD be used. + For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), + individual operations will not all have the same query text, + and 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 = ?', 'SET mykey "WuValue"'] - id: query.parameter type: template[string] @@ -57,6 +82,14 @@ groups: If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. examples: ['someval', '55'] + - id: operation.batch.size + type: int + stability: experimental + brief: The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations). + note: > + Operations are only considered batches when they contain two or more operations, + and so `db.operation.batch.size` SHOULD never be `1`. + examples: [ 2, 3, 4 ] - id: system brief: The database management system (DBMS) product as identified by the client instrumentation. note: > From 8e8700cbb47a904aa1b5cd0517811fd1e8c40a61 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 07:56:28 -0700 Subject: [PATCH 2/8] markdown --- docs/attributes-registry/db.md | 39 ++++++++++++++++++------------- docs/database/cassandra.md | 24 +++++++++++-------- docs/database/cosmosdb.md | 24 +++++++++++-------- docs/database/database-metrics.md | 12 +++++++--- docs/database/database-spans.md | 24 +++++++++++-------- docs/database/elasticsearch.md | 13 +++++++---- docs/database/hbase.md | 3 ++- docs/database/mongodb.md | 3 ++- docs/database/mssql.md | 20 +++++++++------- docs/database/redis.md | 3 ++- docs/database/sql.md | 20 +++++++++------- model/registry/db.yaml | 4 ++-- 12 files changed, 114 insertions(+), 75 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 6b6d3743bb..1465b79c35 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -17,30 +17,37 @@ This group defines the attributes used to describe telemetry in the context of databases. -| Attribute | Type | Description | Examples | Stability | -| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.client.connections.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.name` | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.parameter.` | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [4] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.text` | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `mssql`; `mssqlcompact` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connections.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.batch.size` | int | The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations). [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.name` | string | The name of the operation or command being executed. | +| For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.parameter.` | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [7] | `other_sql`; `mssql`; `mssqlcompact` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[2]:** 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]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +**[3]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. + +**[4]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[4]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[5]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. -**[5]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. +**[6]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. + +**[7]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. `db.client.connections.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -204,9 +211,9 @@ This group defines attributes for Elasticsearch. | ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [6] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[6]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part 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 part values to their names. +**[8]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part 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 part values to their names. ## Db Metrics Deprecated Attributes diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index f16a173170..054af7fbfd 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -25,7 +25,8 @@ described on this page. |---|---|---|---|---|---| | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The Cassandra keyspace name. [3] | `mykeyspace` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`db.cassandra.consistency_level`](/docs/attributes-registry/db.md) | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all`; `each_quorum`; `quorum` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -34,14 +35,15 @@ described on this page. | [`db.cassandra.idempotence`](/docs/attributes-registry/db.md) | boolean | Whether or not the query is idempotent. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cassandra.page_size`](/docs/attributes-registry/db.md) | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cassandra.speculative_execution_count`](/docs/attributes-registry/db.md) | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [10] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [11] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -57,13 +59,15 @@ It is RECOMMENDED to capture the value as provided by the application without at **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[9]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[10]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. +**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. -**[11]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[11]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. -**[12]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[12]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[13]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 76ad96edb2..7adf529287 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -33,18 +33,20 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [10] | `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\|` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [8] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [11] | `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\|` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[2]:** @@ -58,15 +60,17 @@ It is RECOMMENDED to capture the value as provided by the application without at **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[8]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[8]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[9]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[9]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. -**[10]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. +**[10]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[11]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". -**[11]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[12]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 2adf2f24e9..04b517dc51 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -79,7 +79,11 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Batch operations SHOULD be recorded as a single operation. + @@ -99,7 +103,8 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `mssql`; `mssqlcompact` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [10] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -109,7 +114,8 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. **[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. **[2]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[3]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index e3616f3c98..18758aabe5 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -99,19 +99,21 @@ These attributes will usually be the same for all operations performed over the | [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `mssql`; `mssqlcompact` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [11] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [13] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. **[2]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[3]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -129,14 +131,16 @@ It is RECOMMENDED to capture the value as provided by the application without at **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[10]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. + +**[11]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. -**[11]:** 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. +**[12]:** 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. -**[12]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[13]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[13]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[14]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index ccf99bdafd..d626895362 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -32,7 +32,8 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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.elasticsearch.path_parts.`](/docs/attributes-registry/db.md) | string | A dynamic value in the url path. [4] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | `Conditionally Required` when the url has dynamic values | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -40,8 +41,8 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | [`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) | | [`db.elasticsearch.cluster.name`](/docs/attributes-registry/db.md) | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.elasticsearch.node.name`](/docs/attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [10] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** This SHOULD be the endpoint identifier for the request. @@ -76,9 +77,11 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[9]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. -**[10]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. +**[10]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[11]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[11]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. + +**[12]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 91a42579fc..6c30e2738b 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -25,7 +25,8 @@ described on this page. |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`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) | diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 592ed984e5..89c1e636d9 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -31,7 +31,8 @@ described on this page. | [`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]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[2]:** diff --git a/docs/database/mssql.md b/docs/database/mssql.md index ec7e8e56ad..430643bbb7 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -25,15 +25,17 @@ described on this page. |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `instance1.products`; `customers` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -51,11 +53,13 @@ In the case of `EXEC`, this SHOULD be the stored procedure name that is being ex **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[9]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[10]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. -**[11]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[11]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[12]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. diff --git a/docs/database/redis.md b/docs/database/redis.md index c5f5772b4a..6779e6ed3e 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -24,7 +24,8 @@ described on this page. | 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 index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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.query.text`](/docs/attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [7] | `HMSET myhash field1 'Hello' field2 'World'` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/sql.md b/docs/database/sql.md index 7b5473a5b8..b1029c08e5 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -23,15 +23,17 @@ described on this page. |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. -It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. **[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -66,11 +68,13 @@ In the case of `EXEC`, this SHOULD be the stored procedure name that is being ex **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. +**[9]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[10]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. -**[11]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[11]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[12]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. diff --git a/model/registry/db.yaml b/model/registry/db.yaml index e41b3b5102..510b9c07f4 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -10,8 +10,8 @@ groups: stability: experimental brief: The name of a collection (table, container) within the database. note: > - If the collection name is parsed from the query, it SHOULD match the value provided - in the query and may be qualified with the schema and database name. + If the collection name is parsed from the query, it SHOULD match the value provided + in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. From 0a3e1af6d1a4ede3c53577f13678bac55c933cc4 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 07:59:31 -0700 Subject: [PATCH 3/8] changelog --- .chloggen/database-batch-operations.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/database-batch-operations.yaml diff --git a/.chloggen/database-batch-operations.yaml b/.chloggen/database-batch-operations.yaml new file mode 100644 index 0000000000..30beccc95f --- /dev/null +++ b/.chloggen/database-batch-operations.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add support for database batch operations + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [ 712 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From 4e89c6bddaad0ab30faea4dab89bf91cb8d9e6c4 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 08:01:18 -0700 Subject: [PATCH 4/8] words --- docs/database/database-spans.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 18758aabe5..e5174d4945 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -75,13 +75,13 @@ The `{target}` SHOULD adhere to one of the ### Homogeneous batches -Homogeneous batches are batches of two or more operations where the individual operations are known to all have the -same `db.query.text`. +Homogeneous batches are defined as batches of two or more operations +where the individual operations are known to all have the same `db.query.text`. ### Heterogeneous batches -Heterogeneous batches are batches of two or more operations where individual operations are not known to all have the -same `db.query.text`. +Heterogeneous batches are defined batches of two or more operations +where individual operations are not known to all have the same `db.query.text`. ## Common attributes From 977e0d51d39e43863a951bb017c2019b2d440a96 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 08:07:51 -0700 Subject: [PATCH 5/8] toc --- docs/database/database-spans.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index e5174d4945..25fc80efbd 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -11,6 +11,9 @@ linkTitle: Client Calls - [Name](#name) +- [Batch operations](#batch-operations) + - [Homogeneous batches](#homogeneous-batches) + - [Heterogeneous batches](#heterogeneous-batches) - [Common attributes](#common-attributes) - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies) From 26744fe3c5c69174e6ec4bc8f6c4c6391c74288c Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 08:09:52 -0700 Subject: [PATCH 6/8] fix --- docs/attributes-registry/db.md | 24 ++++++++++++------------ docs/database/cassandra.md | 4 ++-- docs/database/cosmosdb.md | 4 ++-- docs/database/database-metrics.md | 4 ++-- docs/database/database-spans.md | 4 ++-- docs/database/elasticsearch.md | 3 +-- docs/database/hbase.md | 4 ++-- docs/database/mssql.md | 3 +-- docs/database/redis.md | 4 ++-- docs/database/sql.md | 3 +-- model/registry/db.yaml | 4 ++-- 11 files changed, 29 insertions(+), 32 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 1465b79c35..54690fc106 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -17,18 +17,17 @@ This group defines the attributes used to describe telemetry in the context of databases. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.client.connections.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.batch.size` | int | The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations). [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.name` | string | The name of the operation or command being executed. | -| For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.parameter.` | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [7] | `other_sql`; `mssql`; `mssqlcompact` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.client.connections.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 `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connections.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.batch.size` | int | The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations). [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.parameter.` | string | The query parameters used in `db.query.text`, with `` being the parameter name, and the attribute value being the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [7] | `other_sql`; `mssql`; `mssqlcompact` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -41,6 +40,7 @@ It is RECOMMENDED to capture the value as provided by the application without at **[3]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[4]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[5]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 054af7fbfd..3e35ef8e1e 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -25,8 +25,7 @@ described on this page. |---|---|---|---|---|---| | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The Cassandra keyspace name. [3] | `mykeyspace` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`db.cassandra.consistency_level`](/docs/attributes-registry/db.md) | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all`; `each_quorum`; `quorum` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -50,6 +49,7 @@ For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous- **[3]:** For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails). **[4]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[5]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 7adf529287..1cf3073d6e 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -33,8 +33,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -51,6 +50,7 @@ For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous- **[2]:** **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 04b517dc51..c3d14e0415 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -103,8 +103,7 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `mssql`; `mssqlcompact` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [10] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -124,6 +123,7 @@ Semantic conventions for individual database systems SHOULD document what `db.na It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[5]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[6]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 25fc80efbd..51bd8ef38c 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -102,8 +102,7 @@ These attributes will usually be the same for all operations performed over the | [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `mssql`; `mssqlcompact` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` [9] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -125,6 +124,7 @@ Semantic conventions for individual database systems SHOULD document what `db.na It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[5]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[6]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index d626895362..4b6ddcdf5c 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -32,8 +32,7 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | 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. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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.elasticsearch.path_parts.`](/docs/attributes-registry/db.md) | string | A dynamic value in the url path. [4] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | `Conditionally Required` when the url has dynamic values | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 6c30e2738b..91a8a75ae2 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -25,8 +25,7 @@ described on this page. |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`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) | @@ -36,6 +35,7 @@ For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous- **[2]:** When performing table-related operations, the instrumentations SHOULD extract the namespace from the table name according to the [HBase table naming conventions](https://hbase.apache.org/book.html#namespace_creation). If namespace is not provided, instrumentation SHOULD set `db.namespace` value to `default`. **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 430643bbb7..f3346dcb7a 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -25,8 +25,7 @@ described on this page. |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `instance1.products`; `customers` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/redis.md b/docs/database/redis.md index 6779e6ed3e..679c8ad7a0 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -24,8 +24,7 @@ described on this page. | 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 index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select). [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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.query.text`](/docs/attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [7] | `HMSET myhash field1 'Hello' field2 'World'` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -39,6 +38,7 @@ Instrumentations SHOULD NOT set this attribute if capturing it would require add For commands that switch the database, this SHOULD be set to the target database (even if the command fails). **[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[3]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/sql.md b/docs/database/sql.md index b1029c08e5..d0d7a9d8be 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -23,8 +23,7 @@ described on this page. |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the SQL table that the operation is acting upon. [1] | `users`; `dbo.products` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [3] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `SELECT`; `INSERT`; `UPDATE`; `DELETE`; `CREATE`; `mystoredproc` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/registry/db.yaml b/model/registry/db.yaml index 510b9c07f4..f3a70467ca 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -44,6 +44,8 @@ groups: stability: experimental brief: > The name of the operation or command being executed. + note: > + It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, @@ -54,8 +56,6 @@ groups: For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. - note: > - It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. examples: ['findAndModify', 'HMSET', 'SELECT'] - id: query.text type: string From bbbc105325118c73991a5f9e4f92b97d1cbb366a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 09:09:57 -0700 Subject: [PATCH 7/8] simplify --- docs/database/database-spans.md | 15 --------------- model/registry/db.yaml | 29 ++++++++--------------------- 2 files changed, 8 insertions(+), 36 deletions(-) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 51bd8ef38c..8a69a6ae21 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -11,9 +11,6 @@ linkTitle: Client Calls - [Name](#name) -- [Batch operations](#batch-operations) - - [Homogeneous batches](#homogeneous-batches) - - [Heterogeneous batches](#heterogeneous-batches) - [Common attributes](#common-attributes) - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies) @@ -74,18 +71,6 @@ The `{target}` SHOULD adhere to one of the - `server.address:server.port` - `db.system` -## Batch operations - -### Homogeneous batches - -Homogeneous batches are defined as batches of two or more operations -where the individual operations are known to all have the same `db.query.text`. - -### Heterogeneous batches - -Heterogeneous batches are defined batches of two or more operations -where individual operations are not known to all have the same `db.query.text`. - ## Common attributes These attributes will usually be the same for all operations performed over the same database connection. diff --git a/model/registry/db.yaml b/model/registry/db.yaml index f3a70467ca..f4ec0ffcff 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -16,12 +16,8 @@ groups: If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. - For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, - that collection name SHOULD be used. - For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, - that collection name SHOULD be used. - For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, - `db.collection.name` SHOULD NOT be captured. + For batch operations, if the individual operations are known to have the same collection name + then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. examples: ['public.users', 'customers'] - id: namespace type: string @@ -47,15 +43,9 @@ groups: note: > It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), - individual operations will all have the same operation name and so that operation name SHOULD be used, - prepended by `BATCH `. - For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) - where individual operations are known to all have the same operation name, that operation name SHOULD be used, - prepended by `BATCH `. - For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) - where individual operations are not known to all have the same operation name, - `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. + 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 system specific term if more applicable. examples: ['findAndModify', 'HMSET', 'SELECT'] - id: query.text type: string @@ -63,12 +53,9 @@ groups: brief: > The database query being executed. note: > - For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), - individual operations will all have the same query text and so that query text SHOULD be used. - For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), - individual operations will not all have the same query text, - and all of the individual query texts SHOULD be concatenated with separator `; ` - or some other database system specific separator if more applicable. + 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 = ?', 'SET mykey "WuValue"'] - id: query.parameter type: template[string] From 79f9ca1369d708936845626ba0e525352c057a43 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 24 May 2024 09:10:50 -0700 Subject: [PATCH 8/8] generate --- docs/attributes-registry/db.md | 6 +++--- docs/database/cassandra.md | 6 +++--- docs/database/cosmosdb.md | 6 +++--- docs/database/database-metrics.md | 4 ++-- docs/database/database-spans.md | 6 +++--- docs/database/elasticsearch.md | 2 +- docs/database/hbase.md | 2 +- docs/database/mongodb.md | 2 +- docs/database/mssql.md | 4 ++-- docs/database/redis.md | 2 +- docs/database/sql.md | 4 ++-- 11 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 54690fc106..06c7647e79 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -31,7 +31,7 @@ This group defines the attributes used to describe telemetry in the context of d **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[2]:** 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. @@ -40,12 +40,12 @@ It is RECOMMENDED to capture the value as provided by the application without at **[3]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[4]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[5]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. -**[6]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[6]:** 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. **[7]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 3e35ef8e1e..355be9cf0a 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -42,14 +42,14 @@ described on this page. **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. **[3]:** For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails). **[4]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[5]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. @@ -59,7 +59,7 @@ For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous- **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[9]:** 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. **[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 1cf3073d6e..6d2333920e 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -45,12 +45,12 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[2]:** **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. @@ -60,7 +60,7 @@ For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous- **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[8]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[8]:** 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. **[9]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index c3d14e0415..c468e11a33 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -114,7 +114,7 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. **[2]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[3]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -123,7 +123,7 @@ Semantic conventions for individual database systems SHOULD document what `db.na It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[5]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[6]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 8a69a6ae21..d883ce1dfb 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -100,7 +100,7 @@ These attributes will usually be the same for all operations performed over the **[2]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[3]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -109,7 +109,7 @@ Semantic conventions for individual database systems SHOULD document what `db.na It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[5]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[6]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. @@ -119,7 +119,7 @@ For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous- **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[10]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[10]:** 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. **[11]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 4b6ddcdf5c..b609d38443 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -76,7 +76,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[9]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. -**[10]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[10]:** 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. **[11]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 91a8a75ae2..c5d5f66d00 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -35,7 +35,7 @@ described on this page. **[2]:** When performing table-related operations, the instrumentations SHOULD extract the namespace from the table name according to the [HBase table naming conventions](https://hbase.apache.org/book.html#namespace_creation). If namespace is not provided, instrumentation SHOULD set `db.namespace` value to `default`. **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 89c1e636d9..26e123f42c 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -32,7 +32,7 @@ described on this page. **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[2]:** diff --git a/docs/database/mssql.md b/docs/database/mssql.md index f3346dcb7a..3a88818499 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -34,7 +34,7 @@ described on this page. **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -52,7 +52,7 @@ In the case of `EXEC`, this SHOULD be the stored procedure name that is being ex **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[9]:** 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. **[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. diff --git a/docs/database/redis.md b/docs/database/redis.md index 679c8ad7a0..763e470c1a 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -38,7 +38,7 @@ Instrumentations SHOULD NOT set this attribute if capturing it would require add For commands that switch the database, this SHOULD be set to the target database (even if the command fails). **[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same operation name and so that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same operation name, that operation name SHOULD be used, prepended by `BATCH `. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same operation name, `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. +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 system specific term if more applicable. **[3]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query. diff --git a/docs/database/sql.md b/docs/database/sql.md index d0d7a9d8be..7a2801cdd3 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -32,7 +32,7 @@ described on this page. **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. -For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), since individual operations will all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are known to all have the same collection name, that collection name SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches) where individual operations are not known to all have the same collection name, `db.collection.name` SHOULD NOT be captured. +For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured. **[2]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.collection.name`, then it SHOULD be the first collection name found in the query. @@ -67,7 +67,7 @@ In the case of `EXEC`, this SHOULD be the stored procedure name that is being ex **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[9]:** For [homogeneous batch operations](/docs/database/database-spans.md#homogeneous-batches), individual operations will all have the same query text and so that query text SHOULD be used. For [heterogeneous batch operations](/docs/database/database-spans.md#heterogeneous-batches), individual operations will not all have the same query text, and all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[9]:** 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. **[10]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information.