Update Azure messaging: settlement attributes and span names

.chloggen/697.yaml

@@ -0,0 +1,7 @@
+change_type: enhancement
+
+component: messaging
+
+note: Clarifies span names for Azure messaging systems and adds `messaging.servicebus.disposition_status attribute`.
+
+issues: [697]

docs/attributes-registry/messaging.md

@@ -157,6 +157,16 @@ size should be used.
 | Attribute  | Type | Description  | Examples  |
 |---|---|---|---|
 | `messaging.servicebus.destination.subscription_name` | string | The name of the subscription in the topic messages are received from. | `mySubscription` |
+| `messaging.servicebus.disposition_status` | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` |
 | `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` |
 | `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` |
+
+`messaging.servicebus.disposition_status` 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 |
+|---|---|
+| `complete` | Message is completed |
+| `abandon` | Message is abandoned |
+| `dead_letter` | Message is sent to dead letter queue |
+| `defer` | Message is deferred |
 <!-- endsemconv -->

docs/messaging/azure-messaging.md

@@ -12,13 +12,23 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu
 
 `messaging.system` MUST be set to `"servicebus"`.
 
+### Span names
+
+The span name SHOULD follow [the general messaging span name pattern](../messaging/azure-messaging.md): it SHOULD start with the messaging destination name (Event Hubs queue or topic name) and contain a low-cardinality name of the operation the span describes:
+
+- Spans names for `settle` operations SHOULD follow the `<destination name> {messaging.servicebus.disposition_status}` pattern.
+  For example, `my-queue complete` or `my-queue abandon`.
+- Spans names for `publish` operations SHOULD follow the `<destination name> send` pattern.
+- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general `<destination name> <operation name>` pattern.
+
 ### Span attributes
 
 The following additional attributes are defined:
 <!-- semconv messaging.servicebus -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`messaging.servicebus.destination.subscription_name`](../attributes-registry/messaging.md) | string | The name of the subscription in the topic messages are received from. | `mySubscription` | Conditionally Required: If messages are received from the subscription. |
+| [`messaging.servicebus.disposition_status`](../attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` | Conditionally Required: if and only if `messaging.operation` is `settle`. |
 | [`messaging.servicebus.message.delivery_count`](../attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | Conditionally Required: [1] |
 | [`messaging.servicebus.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended |
 
@@ -29,6 +39,15 @@ The following additional attributes are defined:
 
 `messaging.system` MUST be set to `"eventhubs"`.
 
+### Span names
+
+The span name SHOULD follow the [general messaging span name pattern](../messaging/azure-messaging.md): it SHOULD start with the messaging destination name (Event Hubs namespace) and
+contain a low-cardinality name of an operation the span describes:
+
+- Spans for `settle` operations SHOULD follow the `<destination name> checkpoint` pattern (matching Event Hubs terminology).
+- Spans names for `publish` operations SHOULD follow the `<destination name> send` pattern.
+- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general `<destination name> <operation name>` pattern.
+
 ### Span attributes
 
 The following additional attributes are defined:

model/registry/messaging.yaml

@@ -298,6 +298,26 @@ groups:
           The name of the subscription in the topic messages are received from.
         examples: "mySubscription"
         tag: tech-specific-servicebus
+      - id: servicebus.disposition_status
+        brief: >
+          Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock).
+        type:
+          allow_custom_values: true
+          members:
+            - id: complete
+              value: 'complete'
+              brief: 'Message is completed'
+            - id: abandon
+              value: 'abandon'
+              brief: 'Message is abandoned'
+            - id: dead_letter
+              value: 'dead_letter'
+              brief: 'Message is sent to dead letter queue'
+            - id: defer
+              value: 'defer'
+              brief: 'Message is deferred'
+        stability: experimental
+        tag: tech-specific-servicebus
       - id: eventhubs.message.enqueued_time
         type: int
         brief: >

model/trace/messaging.yaml

@@ -181,6 +181,9 @@ groups:
       - ref: messaging.servicebus.destination.subscription_name
         requirement_level:
           conditionally_required: If messages are received from the subscription.
+      - ref: messaging.servicebus.disposition_status
+        requirement_level:
+          conditionally_required: if and only if `messaging.operation` is `settle`.
   - id: messaging.eventhubs
     type: attribute_group
     extends: messaging