From 8625d8452de710eaa3b509af5a99883bd424078e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 6 Feb 2024 17:47:59 -0800 Subject: [PATCH 1/7] Update Azure messaging: settlement attributes and span names --- docs/attributes-registry/messaging.md | 10 ++++++++++ docs/messaging/azure-messaging.md | 20 ++++++++++++++++++++ model/registry/messaging.yaml | 19 +++++++++++++++++++ model/trace/messaging.yaml | 3 +++ 4 files changed, 52 insertions(+) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index e53250e0c4..a73514561c 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 [settlement type](https://learn.microsoft.com/en-us/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..a69b4665b1 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -12,6 +12,16 @@ 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 [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 an operation span describes: + +- Spans for `deliver` operation SHOULD follow ` process` pattern (matching terminology used in Azure client libraries) +- Spans for `settle` operation SHOULD follow ` ` pattern. Disposition status MUST match the value of `messaging.servicebus.disposition_status` attribute. + For example, `my-queue complete` or `my-queue abandon` +- Spans for `create`, `receive`, and `publish` operations SHOULD follow general ` ` pattern + ### Span attributes The following additional attributes are defined: @@ -19,6 +29,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 [settlement type](https://learn.microsoft.com/en-us/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 +40,15 @@ The following additional attributes are defined: `messaging.system` MUST be set to `"eventhubs"`. +### Span names + +The span name SHOULD follow [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 span describes: + +- Spans for `deliver` operation SHOULD follow ` process` pattern (matching terminology used in Azure client libraries) +- Spans for `settle` operation SHOULD follow ` checkpoint` (matching Event Hubs terminology) +- Spans for `create`, `receive`, and `publish` operations SHOULD follow general ` ` pattern + ### Span attributes The following additional attributes are defined: diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 33d2d2ac4f..43803af3de 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -298,6 +298,25 @@ 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 [settlement type](https://learn.microsoft.com/en-us/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' + 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 From 794c883f8f94d86c0d5451e252f145f433e2aeb5 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 6 Feb 2024 17:56:00 -0800 Subject: [PATCH 2/7] changelog --- docs/attributes-registry/messaging.md | 2 +- docs/messaging/azure-messaging.md | 2 +- model/registry/messaging.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index a73514561c..4036a0c595 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -157,7 +157,7 @@ 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 [settlement type](https://learn.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` | +| `messaging.servicebus.disposition_status` | string | Describes [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` | diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index a69b4665b1..47f1576fd0 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -29,7 +29,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 [settlement type](https://learn.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` | Conditionally Required: if and only if `messaging.operation` is `settle`. | +| [`messaging.servicebus.disposition_status`](../attributes-registry/messaging.md) | string | Describes [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 | diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 43803af3de..268e62ce35 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -300,7 +300,7 @@ groups: tag: tech-specific-servicebus - id: servicebus.disposition_status brief: > - Describes [settlement type](https://learn.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). + Describes [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). type: allow_custom_values: true members: From 66dd6f9cd2c3fd568df75ea327b286caa9957664 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 6 Feb 2024 18:11:32 -0800 Subject: [PATCH 3/7] changelog --- .chloggen/697.yaml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .chloggen/697.yaml 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] From b7427f8739b8b672965205b04491b3a9c102f454 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 23 Feb 2024 14:53:47 -0800 Subject: [PATCH 4/7] up --- docs/messaging/azure-messaging.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 47f1576fd0..5966bab135 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -16,10 +16,9 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu The span name SHOULD follow [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 an operation span describes: - -- Spans for `deliver` operation SHOULD follow ` process` pattern (matching terminology used in Azure client libraries) -- Spans for `settle` operation SHOULD follow ` ` pattern. Disposition status MUST match the value of `messaging.servicebus.disposition_status` attribute. +- Spans names for `settle` operation SHOULD follow ` {messaging.servicebus.disposition_status}` pattern. For example, `my-queue complete` or `my-queue abandon` +- Spans names for `publish` operation SHOULD follow ` send` pattern. - Spans for `create`, `receive`, and `publish` operations SHOULD follow general ` ` pattern ### Span attributes @@ -45,8 +44,8 @@ The following additional attributes are defined: The span name SHOULD follow [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 span describes: -- Spans for `deliver` operation SHOULD follow ` process` pattern (matching terminology used in Azure client libraries) - Spans for `settle` operation SHOULD follow ` checkpoint` (matching Event Hubs terminology) +- Spans names for `publish` operation SHOULD follow ` send` pattern - Spans for `create`, `receive`, and `publish` operations SHOULD follow general ` ` pattern ### Span attributes From 792a5daebc7066c68902bb6afbcec030b26cda77 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 28 Feb 2024 20:12:00 -0800 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Johannes Tax --- docs/messaging/azure-messaging.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 5966bab135..e022e96cbc 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -14,12 +14,12 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu ### Span names -The span name SHOULD follow [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 an operation span describes: -- Spans names for `settle` operation SHOULD follow ` {messaging.servicebus.disposition_status}` pattern. - For example, `my-queue complete` or `my-queue abandon` -- Spans names for `publish` operation SHOULD follow ` send` pattern. -- Spans for `create`, `receive`, and `publish` operations SHOULD follow general ` ` pattern +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 @@ -28,7 +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 [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.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 | @@ -41,12 +41,12 @@ The following additional attributes are defined: ### Span names -The span name SHOULD follow [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 span describes: +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` operation SHOULD follow ` checkpoint` (matching Event Hubs terminology) -- Spans names for `publish` operation SHOULD follow ` send` pattern -- Spans for `create`, `receive`, and `publish` operations SHOULD follow general ` ` pattern +- 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 From ae1f1613cc82e388c91a1dd678fc523810450183 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 28 Feb 2024 20:17:09 -0800 Subject: [PATCH 6/7] up --- docs/attributes-registry/messaging.md | 2 +- docs/messaging/azure-messaging.md | 4 ++-- model/registry/messaging.yaml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 4036a0c595..c94f5aa3cb 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -157,7 +157,7 @@ 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 [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` | +| `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` | diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index e022e96cbc..e7317d7b3a 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -14,8 +14,8 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu ### 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: +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. diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 268e62ce35..bef2740580 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -300,7 +300,7 @@ groups: tag: tech-specific-servicebus - id: servicebus.disposition_status brief: > - Describes [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). + Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). type: allow_custom_values: true members: From 6e9552e7867c4167f1e4eea67394b3a1103adb99 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 29 Feb 2024 09:54:16 -0800 Subject: [PATCH 7/7] experimental --- model/registry/messaging.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index bef2740580..d05b5cc71d 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -316,6 +316,7 @@ groups: - id: defer value: 'defer' brief: 'Message is deferred' + stability: experimental tag: tech-specific-servicebus - id: eventhubs.message.enqueued_time type: int