diff --git a/.chloggen/768.yaml b/.chloggen/768.yaml new file mode 100644 index 0000000000..7cceacd08b --- /dev/null +++ b/.chloggen/768.yaml @@ -0,0 +1,7 @@ +change_type: breaking + +component: db + +note: Remove `network.transport` and `network.type` attributes from database semantic conventions, clarify when `network.peer.address|port` should be populated. + +issues: [690, 768] diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 6193ee0d21..6e83dd1a69 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -25,11 +25,15 @@ described on this page. | [`db.cassandra.speculative_execution_count`](../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 | | [`db.cassandra.table`](../attributes-registry/db.md) | string | The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | | [`db.name`](../attributes-registry/db.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [3] | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: if and only if `network.peer.address` is set. | **[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. **[2]:** For Cassandra the `db.name` should be set to the Cassandra keyspace name. +**[3]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + `db.cassandra.consistency_level` MUST be one of the following: | Value | Description | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 6324709e0c..a37429f009 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -79,12 +79,10 @@ Some database systems may allow a connection to switch to a different `db.user`, | [`db.statement`](../attributes-registry/db.md) | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [3] | | [`db.system`](../attributes-registry/db.md) | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | [`db.user`](../attributes-registry/db.md) | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `udp` | Recommended | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | Conditionally Required: [8] | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [4] | `10.1.2.80`; `/tmp/my.sock` | Recommended: If applicable for this database system. | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: if and only if `network.peer.address` is set. | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | **[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). @@ -92,19 +90,14 @@ Some database systems may allow a connection to switch to a different `db.user`, **[3]:** Should be collected by default only if there is sanitization that excludes sensitive information. -**[4]:** The value SHOULD be normalized to lowercase. +**[4]:** 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. -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. +**[5]:** 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. -**[5]:** The value SHOULD be normalized to lowercase. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[6]:** 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. - -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. `db.system` 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. @@ -162,22 +155,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `clickhouse` | ClickHouse | | `spanner` | Cloud Spanner | | `trino` | Trino | - -`network.transport` 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. - -| Value | Description | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. | -| `unix` | Unix domain socket | - -`network.type` 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. - -| Value | Description | -|---|---| -| `ipv4` | IPv4 | -| `ipv6` | IPv6 | ### Notes and well-known identifiers for `db.system` diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index e7bd336158..4603978dda 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -32,9 +32,11 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | [`db.operation`](../attributes-registry/db.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required | | [`db.statement`](../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: [5] | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [6] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | Conditionally Required: [9] | -| [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [10] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [7] | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: if and only if `network.peer.address` is set. | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | Conditionally Required: [10] | +| [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [11] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. @@ -61,13 +63,15 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[7]:** 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. +**[7]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. -**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[8]:** 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]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[10]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +**[10]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[11]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. diff --git a/docs/database/redis.md b/docs/database/redis.md index 838d50822e..895a293895 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -19,10 +19,14 @@ described on this page. |---|---|---|---|---| | [`db.redis.database_index`](../attributes-registry/db.md) | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: If other than the default database (`0`). | | [`db.statement`](../attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [1] | `HMSET myhash field1 'Hello' field2 'World'` | Recommended: [2] | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [3] | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: if and only if `network.peer.address` is set. | **[1]:** For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. **[2]:** Should be collected by default only if there is sanitization that excludes sensitive information. + +**[3]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. ## Example diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 5d7d4fc269..e824438bf9 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -1,9 +1,7 @@ groups: - - id: db - type: span - brief: > - This document defines the attributes used to perform database client calls. - span_kind: client + - id: db.common.attributes + type: attribute_group + brief: This group defines the attributes used to perform database client calls. attributes: - ref: db.system requirement_level: required @@ -24,15 +22,41 @@ groups: - ref: server.port requirement_level: conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. + - ref: db.instance.id + requirement_level: + recommended: If different from the `server.address` - ref: network.peer.address + brief: Peer address of the database node where the operation was performed. + requirement_level: + recommended: If applicable for this database system. + note: > + Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. + Network peer address and port are useful when the application interacts with individual database nodes directly. + + If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. - ref: network.peer.port requirement_level: - recommended: If `network.peer.address` is set. - - ref: network.transport - - ref: network.type - - ref: db.instance.id + recommended: if and only if `network.peer.address` is set. + + - id: db.tech_specific.network.attributes + type: attribute_group + brief: This group documents attributes that describe database call along with network information. + extends: db.common.attributes + attributes: + - ref: network.peer.address requirement_level: - recommended: If different from the `server.address` + recommended + note: > + If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + tag: tech-specific + - ref: network.peer.port + tag: tech-specific + + - id: db + type: span + brief: This span defines the attributes used to perform database client calls. + span_kind: client + extends: db.common.attributes - id: db.mssql type: span @@ -45,7 +69,7 @@ groups: - id: db.cassandra type: span - extends: db + extends: db.tech_specific.network.attributes brief: > Attributes for Cassandra attributes: @@ -72,7 +96,7 @@ groups: - id: db.hbase type: span - extends: db + extends: db.common.attributes brief: > Attributes for HBase attributes: @@ -85,7 +109,7 @@ groups: - id: db.couchdb type: span - extends: db + extends: db.common.attributes brief: > Attributes for CouchDB attributes: @@ -103,7 +127,7 @@ groups: - id: db.redis type: span - extends: db + extends: db.tech_specific.network.attributes brief: > Attributes for Redis attributes: @@ -122,7 +146,7 @@ groups: - id: db.mongodb type: span - extends: db + extends: db.common.attributes brief: > Attributes for MongoDB attributes: @@ -132,7 +156,7 @@ groups: - id: db.elasticsearch type: span - extends: db + extends: db.tech_specific.network.attributes brief: > Attributes for Elasticsearch attributes: @@ -177,7 +201,7 @@ groups: - id: db.sql type: span - extends: 'db' + extends: db.common.attributes brief: > Attributes for SQL databases attributes: @@ -186,7 +210,7 @@ groups: - id: db.cosmosdb type: span - extends: db + extends: db.common.attributes prefix: db.cosmosdb brief: > Attributes for Cosmos DB.