Database: clarify network attributes usage on common semconv (#768)

Author: lmolkova

.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]

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 |

docs/database/database-spans.md

@@ -79,32 +79,25 @@ 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).
 
 **[2]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
 
 **[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 |
 <!-- endsemconv -->
 
 ### Notes and well-known identifiers for `db.system`

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.
 

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.
 <!-- endsemconv -->
 
 ## Example

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.