diff --git a/.chloggen/698.yaml b/.chloggen/698.yaml index 27cc4211e4..c12d9d9f2d 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 semantic conventions. +note: Remove `network.transport` and `network.type` attributes from messaging semantic conventions, clarify when `network.peer.address|port` should be populated. issues: [690, 698] diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index 95acf97d64..17b74081a9 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -13,7 +13,7 @@ The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pub ## Span attributes For Google Cloud Pub/Sub, the following additional attributes are defined: - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`messaging.gcp_pubsub.message.ordering_key`](../attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | Conditionally Required: If the message type has an ordering key set. | @@ -31,7 +31,7 @@ flowchart LR; direction LR CA[Span Create A] CB[Span Create B] - P[Span Publish A B] + P[Span Publish A B] end CA-. link .-P; CB-. link .-P; diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 47deec0d23..8b30bb5fae 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -24,7 +24,7 @@ described on this page. For Apache Kafka, the following additional attributes are defined: - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`messaging.kafka.consumer.group`](../attributes-registry/messaging.md) | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index e76da06d3a..655770bd71 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -294,8 +294,10 @@ as described in [Attributes specific to certain messaging systems](#attributes-s | [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended | | [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [13] | `publish` | Required | | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [15] | `80`; `8080`; `443` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the messaging intermediary node operation was performed on. [14] | `10.1.2.80`; `/tmp/my.sock` | Recommended: [15] | +| [`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 | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [16] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [17] | `80`; `8080`; `443` | Recommended | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -340,9 +342,13 @@ size should be used. **[13]:** If a custom value is used, it MUST be of low cardinality. -**[14]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +**[14]:** Network peer address and port are important when the application interacts with individual intermediary nodes directly, for example, when messaging intermediary is self-hosted. Fully managed messaging systems that don't expose information about individual nodes SHOULD NOT set this attribute. Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes should be captured. If a messaging operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. -**[15]:** 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. +**[15]:** If available and known to represent the address of specific intermediary node. + +**[16]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + +**[17]:** 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. `error.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. diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index e2501f0e60..e2d1b095ca 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -17,12 +17,12 @@ described on this page. In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. `messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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. [1] | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the messaging intermediary node operation was performed on. [1] | `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 | **[1]:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 8f4bbca5fb..eb0d8b3d5d 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -16,7 +16,7 @@ described on this page. Specific attributes for Apache RocketMQ are defined below. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`messaging.rocketmq.client_group`](../attributes-registry/messaging.md) | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required | diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index bf5aac78cc..3d35fb9ee6 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -80,29 +80,55 @@ groups: - ref: messaging.message.conversation_id - ref: messaging.message.envelope.size - ref: messaging.message.body.size - - ref: server.address + - ref: network.peer.address + brief: Peer address of the messaging intermediary node operation was performed on. + requirement_level: + recommended: If available and known to represent the address of specific intermediary node. + note: > + Network peer address and port are important when the application interacts with individual intermediary nodes directly, + for example, when messaging intermediary is self-hosted. + Fully managed messaging systems that don't expose information about individual nodes SHOULD NOT set this attribute. + Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes should be captured. + If a messaging 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 and only if `network.peer.address` is set. - - id: messaging.rabbitmq + - id: messaging.tech_specific.network.attributes type: attribute_group + brief: Attributes that describe messaging operation along with network information. extends: messaging + attributes: + - ref: network.peer.address + requirement_level: 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 + requirement_level: recommended + tag: tech-specific + + - id: messaging.rabbitmq + type: attribute_group + extends: messaging.tech_specific.network.attributes brief: > Attributes for RabbitMQ attributes: - ref: messaging.rabbitmq.destination.routing_key requirement_level: conditionally_required: If not empty. - tag: tech-specific-rabbitmq + tag: tech-specific - ref: messaging.rabbitmq.message.delivery_tag requirement_level: conditionally_required: When available. - tag: tech-specific-rabbitmq + tag: tech-specific - ref: network.peer.address note: > If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. - tag: tech-specific-rabbitmq + tag: tech-specific - ref: network.peer.port - tag: tech-specific-rabbitmq + tag: tech-specific - id: messaging.kafka type: attribute_group @@ -111,17 +137,17 @@ groups: Attributes for Apache Kafka attributes: - ref: messaging.kafka.message.key - tag: tech-specific-kafka + tag: tech-specific - ref: messaging.kafka.consumer.group - tag: tech-specific-kafka + tag: tech-specific - ref: messaging.kafka.destination.partition - tag: tech-specific-kafka + tag: tech-specific - ref: messaging.kafka.message.offset - tag: tech-specific-kafka + tag: tech-specific - ref: messaging.kafka.message.tombstone requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. - tag: tech-specific-kafka + tag: tech-specific - id: messaging.rocketmq type: attribute_group @@ -131,30 +157,30 @@ groups: attributes: - ref: messaging.rocketmq.namespace requirement_level: required - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.client_group requirement_level: required - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.message.delivery_timestamp requirement_level: conditionally_required: If the message type is delay and delay time level is not specified. - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.message.delay_time_level requirement_level: conditionally_required: If the message type is delay and delivery timestamp is not specified. - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.message.group requirement_level: conditionally_required: If the message type is FIFO. - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.message.type - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.message.tag - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.message.keys - tag: tech-specific-rocketmq + tag: tech-specific - ref: messaging.rocketmq.consumption_model - tag: tech-specific-rocketmq + tag: tech-specific - id: messaging.gcp_pubsub type: attribute_group extends: messaging @@ -162,7 +188,7 @@ groups: Attributes for Google Cloud Pub/Sub attributes: - ref: messaging.gcp_pubsub.message.ordering_key - tag: tech-specific-gcp-pubsub + tag: tech-specific requirement_level: conditionally_required: If the message type has an ordering key set. - id: messaging.servicebus