diff --git a/.chloggen/698.yaml b/.chloggen/698.yaml index 4b97b77899..27cc4211e4 100644 --- a/.chloggen/698.yaml +++ b/.chloggen/698.yaml @@ -2,6 +2,6 @@ change_type: breaking component: messaging -note: Remove `network.*` attributes from general messaging and database semantic conventions. +note: Remove `network.*` attributes from general messaging semantic conventions. issues: [690, 698] diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index b454ddea8e..d5c2e54d32 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -74,14 +74,26 @@ Some database systems may allow a connection to switch to a different `db.user`, | [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | Recommended: If different from the `server.address` | | [`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 | -| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | +| [`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). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -**[1]:** 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. +**[1]:** The value SHOULD be normalized to lowercase. -**[2]:** 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. +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. -**[3]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** 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. + +**[4]:** 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. + +**[5]:** 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. @@ -139,6 +151,22 @@ Some database systems may allow a connection to switch to a different `db.user`, | `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/mongodb.md b/docs/database/mongodb.md index fabb80eacf..10fdbb785e 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -30,6 +30,9 @@ described on this page. | `db.user` | `"the_user"` | | `server.address` | `"mongodb0.example.com"` | | `server.port` | `27017` | +| `network.peer.address` | `"192.0.2.14"` | +| `network.peer.port` | `27017` | +| `network.transport` | `"tcp"` | | `db.name` | `"shopDb"` | | `db.statement` | not set | | `db.operation` | `"findAndModify"` | diff --git a/docs/database/redis.md b/docs/database/redis.md index b2121e1ab7..2614e494fa 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -36,7 +36,8 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an | `db.system` | `"redis"` | | `db.connection_string` | not set | | `db.user` | not set | -| `server.address` | `"/tmp/redis.sock"` | +| `network.peer.address` | `"/tmp/redis.sock"` | +| `network.transport` | `"unix"` | | `db.name` | not set | | `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` | | `db.operation` | not set | diff --git a/docs/database/sql.md b/docs/database/sql.md index f6e98941ae..6483e36374 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -32,6 +32,9 @@ This is an example of attributes for a MySQL database span: | `db.user` | `"billing_user"` | | `server.address` | `"shopdb.example.com"` | | `server.port` | `3306` | +| `network.peer.address` | `"192.0.2.12"` | +| `network.peer.port` | `3306` | +| `network.transport` | `"tcp"` | | `db.name` | `"ShopDb"` | | `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` | | `db.operation` | `"SELECT"` | diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 1c8f2ec8cc..135d3b21ad 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -22,6 +22,8 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. |---|---|---|---|---| | [`messaging.rabbitmq.destination.routing_key`](../attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | | [`messaging.rabbitmq.message.delivery_tag`](../attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | Conditionally Required: When available. | +| [`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 | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 6b886be56a..a896527ac7 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -36,6 +36,16 @@ groups: tag: connection-level requirement_level: conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. + - ref: network.peer.address + tag: connection-level + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + tag: connection-level + - ref: network.transport + tag: connection-level + - ref: network.type + tag: connection-level - ref: db.instance.id tag: connection-level requirement_level: diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index bc455ad817..36d246429c 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -96,6 +96,10 @@ groups: requirement_level: conditionally_required: When available. tag: tech-specific-rabbitmq + - ref: network.peer.address + tag: tech-specific-rabbitmq + - ref: network.peer.port + tag: tech-specific-rabbitmq - id: messaging.kafka type: attribute_group