From 7d87f77e28101b2a53e22fddf886bcdf6ced42a8 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 2 Oct 2024 13:57:44 -0700 Subject: [PATCH 1/4] Recommend making create spans disableable --- docs/messaging/messaging-spans.md | 14 +++++++++++--- .../messaging/deprecated/registry-deprecated.yaml | 1 + model/messaging/registry.yaml | 1 + model/messaging/spans.yaml | 8 ++++++++ 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 5ffc36c97d..b0ca38d15e 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -238,6 +238,14 @@ into the message. The "Publish" span SHOULD always link to the creation context that was injected into a message either from a "Create" span or as a custom creation context. +When instrumenting library API that always sends a single message, it's +RECOMMENDED to create "Publish" span without "Create" span. + +When instrumenting library API that usually operate with batches, it's +RECOMMENDED to create "Create" span for each message along with the "Publish" span. +It's also RECOMMENDED to provide a configuration option allowing to disable "Create" +span creation. + #### Consumer spans "Receive" spans SHOULD be created for operations of passing messages to the @@ -272,7 +280,7 @@ messages were received). For each message it accounts for, the "Process" or > - 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 +> - It is the only option to correlate producer and consumer(s) when message > consumption can happen in the scope of another ambient context such as a > HTTP server span. @@ -294,8 +302,8 @@ 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 +If instrumentation uses the message creation context as the parent for "Process" +spans in the scope of another valid ambient context, it SHOULD add the ambient context as a link on the "Process" span to preserve the correlation between message processing and that context. diff --git a/model/messaging/deprecated/registry-deprecated.yaml b/model/messaging/deprecated/registry-deprecated.yaml index d5d7305429..a10affcf41 100644 --- a/model/messaging/deprecated/registry-deprecated.yaml +++ b/model/messaging/deprecated/registry-deprecated.yaml @@ -1,6 +1,7 @@ groups: - id: registry.messaging.deprecated type: attribute_group + stability: experimental display_name: Deprecated Messaging Attributes brief: "Describes deprecated messaging attributes." attributes: diff --git a/model/messaging/registry.yaml b/model/messaging/registry.yaml index 7adbba2bc9..5bbdec2872 100644 --- a/model/messaging/registry.yaml +++ b/model/messaging/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.messaging type: attribute_group + stability: experimental display_name: General Messaging Attributes brief: 'Attributes describing telemetry around messaging systems and messaging activities.' attributes: diff --git a/model/messaging/spans.yaml b/model/messaging/spans.yaml index cc10819f8a..10c2721a7c 100644 --- a/model/messaging/spans.yaml +++ b/model/messaging/spans.yaml @@ -1,6 +1,7 @@ groups: - id: attributes.messaging.trace.minimal type: attribute_group + stability: experimental brief: > Defines minimal set of attributes used by all messaging systems. extends: attributes.messaging.common.minimal @@ -29,6 +30,7 @@ groups: - id: messaging type: span + stability: experimental brief: > Defines a full set of attributes used in messaging systems. extends: attributes.messaging.trace.minimal @@ -85,6 +87,7 @@ groups: - id: messaging.network.attributes type: attribute_group + stability: experimental brief: Attributes that describe messaging operation along with network information. extends: attributes.messaging.trace.minimal attributes: @@ -97,6 +100,7 @@ groups: - id: messaging.rabbitmq type: attribute_group + stability: experimental extends: messaging.network.attributes brief: > Attributes for RabbitMQ @@ -114,6 +118,7 @@ groups: - id: messaging.kafka type: attribute_group + stability: experimental extends: attributes.messaging.trace.minimal brief: > Attributes for Apache Kafka @@ -146,6 +151,7 @@ groups: - id: messaging.rocketmq type: attribute_group + stability: experimental extends: attributes.messaging.trace.minimal brief: > Attributes for Apache RocketMQ @@ -208,6 +214,7 @@ groups: - `create` and `receive` for [common messaging operations](/docs/messaging/messaging-spans.md#operation-types) - id: messaging.servicebus type: attribute_group + stability: experimental extends: attributes.messaging.trace.minimal brief: > Attributes for Azure Service Bus @@ -248,6 +255,7 @@ groups: - id: messaging.eventhubs type: attribute_group + stability: experimental extends: attributes.messaging.trace.minimal brief: > Attributes for Azure Event Hubs From a0ddae4ccb204cfdf36f9ce8d8f65b142e95b324 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 3 Oct 2024 11:57:27 -0700 Subject: [PATCH 2/4] Add example --- docs/messaging/messaging-spans.md | 53 +++++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index b0ca38d15e..2af922aca6 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -31,7 +31,8 @@ - [Examples](#examples) - [Topic with multiple consumers](#topic-with-multiple-consumers) - [Batch receiving](#batch-receiving) - - [Batch publishing](#batch-publishing) + - [Batch publishing with "Create" spans](#batch-publishing-with-create-spans) + - [Batch publishing without "Create" spans](#batch-publishing-without-create-spans) @@ -583,11 +584,14 @@ flowchart LR; | `messaging.message.id` | `"a1"` | `"a2"` | | | `messaging.batch.message_count` | | | 2 | -### Batch publishing +### Batch publishing with "Create" spans Given is a publisher that publishes a batch with two messages to a topic "Q" on Kafka, and two different consumers receiving one of the messages. +Instrumentation in this case reports "Create" span for each message and a "Publish" +span that's linked to a "Create" span. + ```mermaid flowchart LR; subgraph PRODUCER @@ -629,4 +633,49 @@ flowchart LR; | `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` | | `messaging.batch.message_count` | | | 2 | | | +### Batch publishing without "Create" spans + +Given is a publisher that publishes a batch with two messages to a topic "Q" on +Kafka, and two different consumers receiving one of the messages. + +Based on the configuration provided by user, instrumentation in this case reports +"Publish" span only. It injects "Publish" span context into both messages. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction TB + P[Span Publish] + end + subgraph CONSUMER1 + direction TB + D1[Span Receive A] + end + subgraph CONSUMER2 + direction TB + D2[Span Receive B] + end + P-. link .-D1; + P-. link .-D2; + + classDef normal fill:green + class P,D1,D2 normal + linkStyle 0,1 color:green,stroke:green +``` + +| Field or Attribute | Span Publish | Span Receive A | Span Receive B | +|-|-|-|-| +| Span name | `send Q` | `poll Q` | `poll Q` | +| Parent | | | | +| Links | | Span Publish | Span Publish | +| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | +| `server.address` | `"ms"` | `"ms"` | `"ms"` | +| `server.port` | `1234` | `1234` | `1234` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | +| `messaging.operation.name` | `"send"` | `"poll"` | `"poll"` | +| `messaging.operation.type` | `"publish"` | `"receive"` | `"receive"` | +| `messaging.message.id` | | `"a1"` | `"a2"` | +| `messaging.batch.message_count`| 2 | | | + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From 526136de920ed02b92291311268d48f58c8c9c4f Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 3 Oct 2024 12:02:47 -0700 Subject: [PATCH 3/4] changelog --- .chloggen/1446.yaml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .chloggen/1446.yaml diff --git a/.chloggen/1446.yaml b/.chloggen/1446.yaml new file mode 100644 index 0000000000..fc58cbf997 --- /dev/null +++ b/.chloggen/1446.yaml @@ -0,0 +1,6 @@ +change_type: enhancement +component: messaging +note: > + Add recommendation to report "Create" spans for batch send calls only and + to allow to disable "Create" spans. +issues: [ 1273 ] From ac02a6da633f9058c5d7c847ed4e799efc41be91 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 7 Oct 2024 10:03:32 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/messaging/messaging-spans.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 2af922aca6..572cb6bdf5 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -239,12 +239,12 @@ into the message. The "Publish" span SHOULD always link to the creation context that was injected into a message either from a "Create" span or as a custom creation context. -When instrumenting library API that always sends a single message, it's +When instrumenting a library API that always sends a single message, it is RECOMMENDED to create "Publish" span without "Create" span. -When instrumenting library API that usually operate with batches, it's -RECOMMENDED to create "Create" span for each message along with the "Publish" span. -It's also RECOMMENDED to provide a configuration option allowing to disable "Create" +When instrumenting a library API that usually operate with batches, it is +RECOMMENDED to create a "Create" span for each message along with the "Publish" span. +It is also RECOMMENDED to provide a configuration option allowing to disable "Create" span creation. #### Consumer spans