Merge branch 'main' into cf-resource

open-telemetry · Sep 20, 2024 · aa62acd · aa62acd
2 parents 542124d + 13373cb
commit aa62acd
Show file tree

Hide file tree

Showing 5 changed files with 71 additions and 16 deletions.
diff --git a/.chloggen/fix-deprecated-messaging-servicebus.yaml b/.chloggen/fix-deprecated-messaging-servicebus.yaml
@@ -0,0 +1,4 @@
+change_type: 'bug_fix'
+component: messaging
+note: Fix deprecated note for service bus attributes
+issues: [1418]
diff --git a/.chloggen/messaging-parent-child-trace.yaml b/.chloggen/messaging-parent-child-trace.yaml
@@ -0,0 +1,4 @@
+change_type: enhancement
+component: messaging
+note: Clarify the possibility to have a parent-child trace structure in messaging conventions
+issues: [1282]
diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md
@@ -180,15 +180,15 @@ This group describes attributes specific to Azure Service Bus.
 
 Describes deprecated messaging attributes.
 
-| Attribute                                            | Type    | Description                                                                   | Examples                          | Stability                                                                                                                                                            |
-| ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `messaging.client_id`                                | string  | Deprecated, use `messaging.client.id` instead.                                | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.client.id`.                                                                    |
-| `messaging.destination_publish.anonymous`            | boolean | Deprecated, no replacement at this time.                                      |                                   | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>No replacement at this time.                                                                          |
-| `messaging.destination_publish.name`                 | string  | Deprecated, no replacement at this time.                                      | `MyQueue`; `MyTopic`              | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>No replacement at this time.                                                                          |
-| `messaging.eventhubs.consumer.group`                 | string  | Deprecated, use `messaging.consumer.group.name` instead.                      | `$Default`                        | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name`.                                                          |
-| `messaging.kafka.consumer.group`                     | string  | Deprecated, use `messaging.consumer.group.name` instead.                      | `my-group`                        | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name`.                                                          |
-| `messaging.kafka.destination.partition`              | int     | Deprecated, use `messaging.destination.partition.id` instead.                 | `2`                               | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.destination.partition.id`.                                                     |
-| `messaging.kafka.message.offset`                     | int     | Deprecated, use `messaging.kafka.offset` instead.                             | `42`                              | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.kafka.offset`.                                                                 |
-| `messaging.operation`                                | string  | Deprecated, use `messaging.operation.type` instead.                           | `publish`; `create`; `process`    | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.operation.type`.                                                               |
-| `messaging.rocketmq.client_group`                    | string  | Deprecated, use `messaging.consumer.group.name` instead.                      | `myConsumerGroup`                 | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. |
-| `messaging.servicebus.destination.subscription_name` | string  | Deprecated, use `messaging.servicebus.destination.subscription_name` instead. | `subscription-a`                  | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.servicebus.destination.subscription_name`.                                     |
+| Attribute                                            | Type    | Description                                                        | Examples                          | Stability                                                                                                                                                            |
+| ---------------------------------------------------- | ------- | ------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `messaging.client_id`                                | string  | Deprecated, use `messaging.client.id` instead.                     | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.client.id`.                                                                    |
+| `messaging.destination_publish.anonymous`            | boolean | Deprecated, no replacement at this time.                           |                                   | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>No replacement at this time.                                                                          |
+| `messaging.destination_publish.name`                 | string  | Deprecated, no replacement at this time.                           | `MyQueue`; `MyTopic`              | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>No replacement at this time.                                                                          |
+| `messaging.eventhubs.consumer.group`                 | string  | Deprecated, use `messaging.consumer.group.name` instead.           | `$Default`                        | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name`.                                                          |
+| `messaging.kafka.consumer.group`                     | string  | Deprecated, use `messaging.consumer.group.name` instead.           | `my-group`                        | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name`.                                                          |
+| `messaging.kafka.destination.partition`              | int     | Deprecated, use `messaging.destination.partition.id` instead.      | `2`                               | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.destination.partition.id`.                                                     |
+| `messaging.kafka.message.offset`                     | int     | Deprecated, use `messaging.kafka.offset` instead.                  | `42`                              | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.kafka.offset`.                                                                 |
+| `messaging.operation`                                | string  | Deprecated, use `messaging.operation.type` instead.                | `publish`; `create`; `process`    | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.operation.type`.                                                               |
+| `messaging.rocketmq.client_group`                    | string  | Deprecated, use `messaging.consumer.group.name` instead.           | `myConsumerGroup`                 | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. |
+| `messaging.servicebus.destination.subscription_name` | string  | Deprecated, use `messaging.destination.subscription.name` instead. | `subscription-a`                  | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.destination.subscription.name`.                                                |
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
@@ -25,6 +25,7 @@
   - [Trace structure](#trace-structure)
     - [Producer spans](#producer-spans)
     - [Consumer spans](#consumer-spans)
+      - [Message creation context as parent of "Process" span](#message-creation-context-as-parent-of-process-span)
 - [Messaging attributes](#messaging-attributes)
   - [Recording per-message attributes on batch operations](#recording-per-message-attributes-on-batch-operations)
 - [Examples](#examples)
@@ -261,12 +262,56 @@ batch of messages, or for no message at all (if it is signalled that no
 messages were received). For each message it accounts for, the "Process" or
 "Receive" span SHOULD link to the message's creation context.
 
+> [!IMPORTANT]
+> These conventions use spans links as the default mechanism to correlate
+> producers and consumer(s) because:
+>
+> - It is the only consistent trace structure that can be guaranteed,
+> given the many different messaging systems models available.
+>
+> - It is the only option to correlate producer and consumer(s) in batch scenarios
+> as a span can only have a single parent.
+>
+> - It is the only option to correlate produce and consumer(s) when message
+> consumption can happen in the scope of another ambient context such as a
+> HTTP server span.
+
 "Settle" spans SHOULD be created for every manually or automatically triggered
 settlement operation. A single "Settle" span can account for a single message
 or for multiple messages (in case messages are passed for settling as batches).
 For each message it accounts for, the "Settle" span MAY link to the creation
 context of the message.
 
+##### Message creation context as parent of "Process" span
+
+Exclusively for single messages scenarios, the "Process" span MAY
+use the message's creation context as its parent, thus achieving a direct
+parent-child relationship between producer and consumer(s).
+Instrumentations SHOULD document whether they use the message creation context
+as a parent for "Process" spans and MAY provide configuration options
+allowing users to control this behavior.
+
+It is NOT RECOMMENDED to use the message creation context as the parent of "Process"
+spans (by default) if processing happens in the scope of another span.
+
+If instrumentation use the message creation context as the parent for "Process"
+spans in the scope of another valid ambient context, they SHOULD add the
+ambient context as a link on the "Process" span to preserve the correlation
+between message processing and that context.
+
+For example, a messaging broker pushes messages over HTTP to a consumer
+application which has HTTP server and messaging instrumentations enabled.
+
+The messaging instrumentation would create the "Process" span following
+one of these possible approaches:
+
+- "Process" span is a child of the HTTP server span context and has a link
+  to the message creation context. This is the default behavior.
+
+- "Process" span is a child of the message creation context and has two links:
+  one to the message creation context and another one to HTTP server span context.
+  This is an opt-in behavior.
+
 ## Messaging attributes
 
 Messaging attributes are organized into the following namespaces:
@@ -467,17 +512,19 @@ flowchart LR;
   R2[Span Process A 2]
   end
   P-. link .-R1;
+  P-- parent -->R1;
   P-. link .-R2;
+  P-- parent -->R2;
 
   classDef normal fill:green
   class P,R1,R2 normal
-  linkStyle 0,1 color:green,stroke:green
+  linkStyle 0,1,2,3 color:green,stroke:green
 ```
 
 | Field or Attribute | Span Publish A | Span Process A 1| Span Process A 2 |
 |-|-|-|-|
 | Span name | `publish T` | `consume T` | `consume T` |
-| Parent | | | |
+| Parent (optional) | | `publish T` | `publish T` |
 | Links |  | `publish T` | `publish T` |
 | SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` |
 | `server.address` | `"ms"` | `"ms"` | `"ms"` |

diff --git a/model/messaging/deprecated/registry-deprecated.yaml b/model/messaging/deprecated/registry-deprecated.yaml
@@ -49,10 +49,10 @@ groups:
       - id: messaging.servicebus.destination.subscription_name
         type: string
         brief: >
-          Deprecated, use `messaging.servicebus.destination.subscription_name` instead.
+          Deprecated, use `messaging.destination.subscription.name` instead.
         stability: experimental
         examples: 'subscription-a'
-        deprecated: "Replaced by `messaging.servicebus.destination.subscription_name`."
+        deprecated: "Replaced by `messaging.destination.subscription.name`."
       - id: messaging.kafka.message.offset
         type: int
         stability: experimental