Skip to content

Commit

Permalink
Bring network.peer.* back to general messaging, clarify when to set them
Browse files Browse the repository at this point in the history
  • Loading branch information
lmolkova committed Mar 9, 2024
1 parent 2b6bade commit 823e6e0
Show file tree
Hide file tree
Showing 7 changed files with 64 additions and 32 deletions.
2 changes: 1 addition & 1 deletion .chloggen/698.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
4 changes: 2 additions & 2 deletions docs/messaging/gcp-pubsub.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
<!-- semconv messaging.gcp_pubsub(full,tag=tech-specific-gcp-pubsub) -->
<!-- semconv messaging.gcp_pubsub(full,tag=tech-specific) -->
| 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. |
Expand All @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion docs/messaging/kafka.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ described on this page.

For Apache Kafka, the following additional attributes are defined:

<!-- semconv messaging.kafka(full,tag=tech-specific-kafka) -->
<!-- semconv messaging.kafka(full,tag=tech-specific) -->
| 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 |
Expand Down
14 changes: 10 additions & 4 deletions docs/messaging/messaging-spans.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/messaging/rabbitmq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- semconv messaging.rabbitmq(full,tag=tech-specific-rabbitmq) -->
<!-- semconv messaging.rabbitmq(full,tag=tech-specific) -->
| 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.
Expand Down
2 changes: 1 addition & 1 deletion docs/messaging/rocketmq.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ described on this page.

Specific attributes for Apache RocketMQ are defined below.

<!-- semconv messaging.rocketmq(full,tag=tech-specific-rocketmq) -->
<!-- semconv messaging.rocketmq(full,tag=tech-specific) -->
| 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 |
Expand Down
68 changes: 47 additions & 21 deletions model/trace/messaging.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -131,38 +157,38 @@ 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
brief: >
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
Expand Down

0 comments on commit 823e6e0

Please sign in to comment.