Define sampling relevant attributes for messaging client spans (#1169)

Co-authored-by: Trask Stalnaker <[email protected]>

.chloggen/1169.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: messaging
+note: Define sampling relevant attributes for messaging client spans
+issues: [ 432, 1169 ]

docs/messaging/azure-messaging.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu
 
 ## Azure Service Bus
 
-`messaging.system` MUST be set to `"servicebus"`.
+`messaging.system` MUST be set to `"servicebus"` and SHOULD be provided **at span creation time**.
 
 ### Span attributes
 
@@ -88,6 +88,16 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |
@@ -124,7 +134,7 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
 
 ## Azure Event Hubs
 
-`messaging.system` MUST be set to `"eventhubs"`.
+`messaging.system` MUST be set to `"eventhubs"` and SHOULD be provided **at span creation time**.
 
 ### Span attributes
 
@@ -199,6 +209,17 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |

docs/messaging/gcp-pubsub.md

@@ -8,7 +8,7 @@ linkTitle: Google Cloud Pub/Sub
 
 The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page.
 
-`messaging.system` MUST be set to `"gcp_pubsub"`.
+`messaging.system` MUST be set to `"gcp_pubsub"` and SHOULD be provided **at span creation time**.
 
 ## Span attributes
 
@@ -83,6 +83,16 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |

docs/messaging/kafka.md

@@ -18,7 +18,7 @@ The Semantic Conventions for [Apache Kafka](https://kafka.apache.org/) extend an
 that describe common messaging operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`messaging.system` MUST be set to `"kafka"`.
+`messaging.system` MUST be set to `"kafka"` and SHOULD be provided **at span creation time**.
 
 ## Span attributes
 
@@ -93,6 +93,17 @@ body size should be used.
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |

docs/messaging/messaging-spans.md

@@ -386,6 +386,20 @@ If a messaging operation involved multiple network calls (for example retries),
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.template`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`messaging.system`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |
@@ -455,6 +469,11 @@ the broker doesn't have such notion, the original destination name SHOULD unique
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.destination_publish.name`](/docs/attributes-registry/messaging.md)
+
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->

docs/messaging/rabbitmq.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and ov
 that describe common messaging operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`messaging.system` MUST be set to `"rabbitmq"`.
+`messaging.system` MUST be set to `"rabbitmq"` and SHOULD be provided **at span creation time**.
 
 ## RabbitMQ attributes
 
@@ -78,6 +78,15 @@ body size should be used.
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |

docs/messaging/rocketmq.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [Apache RocketMQ](https://rocketmq.apache.org/) ext
 that describe common messaging operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`messaging.system` MUST be set to `"rocketmq"`.
+`messaging.system` MUST be set to `"rocketmq"` and SHOULD be provided **at span creation time**.
 
 ## Apache RocketMQ attributes
 
@@ -89,6 +89,16 @@ body size should be used.
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.destination.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.name`](/docs/attributes-registry/messaging.md)
+* [`messaging.operation.type`](/docs/attributes-registry/messaging.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `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.
 
 | Value  | Description | Stability |

model/trace/messaging.yaml

@@ -17,6 +17,7 @@ groups:
       In other cases, destination attributes may be set on links.
     attributes:
       - ref: messaging.destination_publish.name
+        sampling_relevant: true
       - ref: messaging.destination_publish.anonymous
 
   - id: attributes.messaging.trace.minimal
@@ -27,15 +28,25 @@ groups:
     attributes:
       - ref: messaging.operation.name
         requirement_level: required
+        sampling_relevant: true
       - ref: messaging.operation.type
         requirement_level:
           conditionally_required: If applicable.
+        sampling_relevant: true
       - ref: messaging.destination.name
         requirement_level:
           conditionally_required: If span describes operation on a single message or if the value applies to all messages in the batch.
+        sampling_relevant: true
       - ref: messaging.message.id
         requirement_level:
           recommended: If span describes operation on a single message.
+      - ref: server.address
+        sampling_relevant: true
+      - ref: server.port
+        sampling_relevant: true
+    # TODO: add messaging.system once https://github.com/open-telemetry/build-tools/issues/192 is implemented
+    # - ref: messaging.system
+    #   sampling_relevant: true
 
   - id: messaging
     type: span
@@ -45,16 +56,19 @@ groups:
     attributes:
       - ref: messaging.system
         requirement_level: required
+        sampling_relevant: true
       - ref: messaging.client.id
         requirement_level: recommended
       - ref: messaging.destination.partition.id
         requirement_level:
           recommended: When applicable.
+        sampling_relevant: true
       - ref: messaging.destination.template
         requirement_level:
           conditionally_required: >
             If available. Instrumentations MUST NOT use `messaging.destination.name` as template
             unless low-cardinality of destination name is guaranteed.
+        sampling_relevant: true
       - ref: messaging.destination.temporary
         requirement_level:
           conditionally_required: If value is `true`. When missing, the value is assumed to be `false`.
@@ -64,9 +78,11 @@ groups:
       - ref: messaging.consumer.group.name
         requirement_level:
           conditionally_required: If applicable.
+        sampling_relevant: true
       - ref: messaging.destination.subscription.name
         requirement_level:
           conditionally_required: If applicable.
+        sampling_relevant: true
       - ref: messaging.message.conversation_id
       - ref: messaging.message.envelope.size
       - ref: messaging.message.body.size
@@ -126,10 +142,12 @@ groups:
       - ref: messaging.consumer.group.name
         brief: "Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html)."
         note: ""
+        sampling_relevant: true
       - ref: messaging.destination.partition.id
         brief: >
           String representation of the partition id the message (or batch) is sent to or received from.
         requirement_level: recommended
+        sampling_relevant: true
       - ref: messaging.kafka.message.key
         requirement_level:
           recommended: If span describes operation on a single message.
@@ -156,6 +174,7 @@ groups:
       - ref: messaging.consumer.group.name
         brief: "RocketMQ [consumer group name](https://rocketmq.apache.org/docs/domainModel/07consumergroup)."
         note: ""
+        sampling_relevant: true
         requirement_level: required
       - ref: messaging.rocketmq.namespace
         requirement_level: required
@@ -188,6 +207,7 @@ groups:
       - ref: messaging.destination.subscription.name
         brief: "Google Pub/Sub [subscription name](https://cloud.google.com/pubsub/docs/subscription-overview)."
         note: ""
+        sampling_relevant: true
       - ref: messaging.gcp_pubsub.message.ordering_key
         requirement_level:
           conditionally_required: If the message type has an ordering key set.
@@ -216,6 +236,7 @@ groups:
       - ref: messaging.destination.subscription.name
         brief: "Azure Service Bus [subscription name](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions)."
         note: ""
+        sampling_relevant: true
         requirement_level:
           conditionally_required: If messages are received from the subscription.
       - ref: messaging.servicebus.message.delivery_count
@@ -257,11 +278,13 @@ groups:
         note: ""
         requirement_level:
           conditionally_required: On consumer spans.
+        sampling_relevant: true
       - ref: messaging.destination.partition.id
         brief: >
           String representation of the partition id messages are sent to or received from, unique within the Event Hub.
         requirement_level:
           conditionally_required: If available.
+        sampling_relevant: true
       - ref: messaging.eventhubs.message.enqueued_time
       - ref: messaging.batch.message_count
         requirement_level: