Merge branch 'main' into messaging-span-kinds

Author: joaopgrassi

.chloggen/1168.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: messaging
+note: Clarify how per-message attributes should be recorded for batch operations.
+issues: [ 1168 ]

docs/messaging/README.md

@@ -22,5 +22,7 @@ Technology specific semantic conventions are defined for the following messaging
 * [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*.
 * [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*.
 * [Google Cloud Pub/Sub](gcp-pubsub.md): Semantic Conventions for *Google Cloud Pub/Sub*.
+* [Azure Service Bus](azure-messaging.md#azure-service-bus): Semantic Conventions for *Azure Service Bus*.
+* [Azure Event Hubs](azure-messaging.md#azure-event-hubs): Semantic Conventions for *Azure Event Hubs*.
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/messaging/messaging-spans.md

@@ -27,13 +27,11 @@
     - [Consumer spans](#consumer-spans)
 - [Messaging attributes](#messaging-attributes)
   - [Consumer attributes](#consumer-attributes)
-  - [Per-message attributes](#per-message-attributes)
-  - [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems)
+  - [Recording per-message attributes on batch operations](#recording-per-message-attributes-on-batch-operations)
 - [Examples](#examples)
   - [Topic with multiple consumers](#topic-with-multiple-consumers)
   - [Batch receiving](#batch-receiving)
   - [Batch publishing](#batch-publishing)
-- [Semantic Conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies)
 
 <!-- tocstop -->
 
@@ -179,7 +177,7 @@ Messaging spans SHOULD follow the overall [guidelines for span names](https://gi
 The **span name** SHOULD be `{messaging.operation.name} {destination}` (see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder).
 <!-- markdown-link-check-enable -->
 
-Semantic conventions for individual messaging systems MAY specify different span name format and then MUST document it in [semantic conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies).
+Semantic conventions for individual messaging systems MAY specify different span name format and then MUST document it in semantic conventions for specific messaging technologies.
 
 The <span id="destination-placeholder">`{destination}`</span> SHOULD describe the entity that the operation is performed against
 and SHOULD adhere to one of the following values, provided they are accessible:
@@ -282,14 +280,13 @@ context of the message.
 
 Messaging attributes are organized into the following namespaces:
 
-- `messaging.message`: Contains [per-message attributes](#per-message-attributes) that describe individual messages. Those attributes are relevant only for spans or links that represent a single message.
+- `messaging.message`: Contains attributes that describe individual messages.
 - `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details.
 - `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details.
 - `messaging.batch`: Contains attributes that describe batch operations.
 - `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details.
 
-Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace
-as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems).
+Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace.
 
 <!-- semconv messaging(full) -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -458,24 +455,18 @@ the broker doesn't have such notion, the original destination name SHOULD unique
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Per-message attributes
+### Recording per-message attributes on batch operations
 
 All messaging operations (`publish`, `receive`, `process`, or others not covered by this specification) can describe both single and/or batch of messages.
-Attributes in the `messaging.message` or `messaging.{system}.message` namespace describe individual messages. For single-message operations they SHOULD be set on corresponding span.
+Attributes in the `messaging.message` or `messaging.{system}.message` namespace apply to individual messages and typically vary between messages within the same batch.
 
-For batch operations, per-message attributes are usually different and cannot be set on the corresponding span. In such cases the attributes SHOULD be set on links. See [Batch receiving](#batch-receiving) for more information on correlation using links.
+Some messaging systems such as Kafka or Azure Event Grid allow publishing a batch of messages to different topics in a single operation, resulting in
+different `messaging.destination.name` or other destination attributes within a single messaging operation.
 
-Some messaging systems (e.g., Kafka, Azure EventGrid) allow publishing a single batch of messages to different topics. In such cases, the attributes in `messaging.destination` MAY be
-set on links. Instrumentations MAY set destination attributes on the span if all messages in the batch share the same destination.
+If the attribute value is the same for all messages in the batch, the instrumentation SHOULD set such attribute on the span representing the batch operation.
+If the attribute values vary, the instrumentation SHOULD set such attributes on links describing individual messages.
 
-### Attributes specific to certain messaging systems
-
-All attributes that are specific for a messaging system SHOULD be populated in `messaging.{system}` namespace. Attributes that describe a message, a destination, a consumer, or a batch of messages SHOULD be populated under the corresponding namespace:
-
-* `messaging.{system}.message.*`: Describes attributes for individual messages
-* `messaging.{system}.destination.*`: Describes the destination a message (or a batch) are published to and received from respectively. The combination of attributes in these namespaces should uniquely identify the entity and include properties significant for this messaging system. For example, Kafka instrumentations should include partition identifier.
-* `messaging.{system}.consumer.*`: Describes message consumer properties
-* `messaging.{system}.batch.*`: Describes message batch properties
+See [Batch receiving](#batch-receiving) for more information on correlation using links.
 
 ## Examples
 
@@ -613,12 +604,4 @@ flowchart LR;
 | `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` |
 | `messaging.batch.message_count` | | | 2 | | |
 
-## Semantic Conventions for specific messaging technologies
-
-More specific Semantic Conventions are defined for the following messaging technologies:
-
-* [Kafka](kafka.md): Semantic Conventions for *Apache Kafka*.
-* [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*.
-* [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*.
-
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

model/trace/messaging.yaml

@@ -1,32 +1,4 @@
 groups:
-  - id: messaging.message
-    type: attribute_group
-    brief: 'Semantic convention describing per-message attributes populated on messaging spans or links.'
-    attributes:
-      - ref: messaging.destination.name
-      - ref: messaging.message.id
-      - ref: messaging.message.conversation_id
-      - ref: messaging.message.envelope.size
-      - ref: messaging.message.body.size
-
-  - id: messaging.destination
-    type: attribute_group
-    brief: 'Semantic convention for attributes that describe messaging destination on broker'
-    note: |
-      Destination attributes should be set on publish, receive, or other spans
-      describing messaging operations.
-
-      Destination attributes should be set when the messaging operation handles
-      single messages. When the operation handles a batch of messages,
-      the destination attributes should only be applied when the attribute value
-      applies to all messages in the batch.
-      In other cases, destination attributes may be set on links.
-    attributes:
-      - ref: messaging.destination.name
-      - ref: messaging.destination.template
-      - ref: messaging.destination.temporary
-      - ref: messaging.destination.anonymous
-
   - id: messaging.destination_publish
     prefix: messaging.destination_publish
     type: attribute_group