From 7d87f77e28101b2a53e22fddf886bcdf6ced42a8 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 2 Oct 2024 13:57:44 -0700 Subject: [PATCH] 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