diff --git a/.chloggen/697.yaml b/.chloggen/697.yaml new file mode 100644 index 0000000000..e6bb861718 --- /dev/null +++ b/.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] diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index e53250e0c4..c94f5aa3cb 100644 --- a/docs/attributes-registry/messaging.md +++ b/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 | diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 35e17ec2c3..e7317d7b3a 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -12,6 +12,15 @@ 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 ` {messaging.servicebus.disposition_status}` pattern. + For example, `my-queue complete` or `my-queue abandon`. +- Spans names for `publish` operations SHOULD follow the ` send` pattern. +- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` pattern. + ### Span attributes The following additional attributes are defined: @@ -19,6 +28,7 @@ The following additional attributes are defined: | 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 ` checkpoint` pattern (matching Event Hubs terminology). +- Spans names for `publish` operations SHOULD follow the ` send` pattern. +- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` pattern. + ### Span attributes The following additional attributes are defined: diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 33d2d2ac4f..d05b5cc71d 100644 --- a/model/registry/messaging.yaml +++ b/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: > diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 6252c0830b..f5b08b74f8 100644 --- a/model/trace/messaging.yaml +++ b/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