diff --git a/CHANGELOG.md b/CHANGELOG.md index 66599ff02fb..f10490a9ae8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,8 @@ release. ([#2706](https://github.com/open-telemetry/opentelemetry-specification/pull/2706)) - Add exceptions to the logs semantic conventions ([#2819](https://github.com/open-telemetry/opentelemetry-specification/pull/2819)) +- Make context propagation requirements explicit for messaging semantic conventions + ([#2750](https://github.com/open-telemetry/opentelemetry-specification/pull/2750)). ### Compatibility diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 831165d9859..0c7d8eec90f 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -7,11 +7,16 @@ - [Definitions](#definitions) + * [Message](#message) + * [Producer](#producer) + * [Consumer](#consumer) + * [Intermediary](#intermediary) * [Destinations](#destinations) * [Message consumption](#message-consumption) * [Conversations](#conversations) * [Temporary destinations](#temporary-destinations) - [Conventions](#conventions) + * [Context propagation](#context-propagation) * [Span name](#span-name) * [Span kind](#span-kind) * [Operation names](#operation-names) @@ -30,6 +35,8 @@ ## Definitions +### Message + Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS): A *message* is an envelope with a potentially empty payload. @@ -43,6 +50,27 @@ With Apache Kafka, the physical broker a message is written to depends on the nu Messages can be delivered to 0, 1, or multiple consumers depending on the dispatching semantic of the protocol. +### Producer + +The "producer" is a specific instance, process or device that creates and +publishes a message. "Publishing" is the process of sending a message or batch +of messages to the intermediary or consumer. + +### Consumer + +A "consumer" receives the message and acts upon it. It uses the context and +data to execute some logic, which might lead to the occurrence of new events. + +The consumer receives, processes, and settles a message. "Receiving" is the +process of obtaining a message from the intermediary, "processing" is the +process of acting on the information a message contains, "settling" is the +process of notifying an intermediary that a message was processed successfully. + +### Intermediary + +An "intermediary" receives a message to forward it to the next receiver, which +might be another intermediary or a consumer. + ### Destinations A destination is usually identified by some name unique within the messaging system instance, which might look like a URL or a simple one-word identifier. @@ -80,6 +108,38 @@ Often such destinations are unnamed or have an auto-generated name. Given these definitions, the remainder of this section describes the semantic conventions for Spans describing interactions with messaging systems. +### Context propagation + +A message may traverse many different components and layers in one or more intermediaries +when it is propagated from the producer to the consumer(s). To be able to correlate +consumer traces with producer traces using the existing context propagation mechanisms, +all components must propagate context down the chain. + +Messaging systems themselves may trace messages as the messages travels from +producers to consumers. Such tracing would cover the transport layer but would +not help in correlating producers with consumers. To be able to directly +correlate producers with consumers, another context that is propagated with +the message is required. + +A message *creation context* allows correlating producers with consumers +of a message and model the dependencies between them, +regardless of the underlying messaging transport mechanism and its instrumentation. + +The message creation context is created by the producer and should be propagated +to the consumer(s). Consumer traces cannot be directly correlated with producer +traces if the message creation context is not attached and propagated with the message. + +A producer SHOULD attach a message creation context to each message. +If possible, the message creation context SHOULD be attached +in such a way that it cannot be changed by intermediaries. + +> This document does not specify the exact mechanisms on how the creation context +> is attached/extracted to/from messages. Future versions of these conventions +> will give clear recommendations, following industry standards including, but not limited to +> [Trace Context: AMQP protocol](https://w3c.github.io/trace-context-amqp/) and +> [Trace Context: MQTT protocol](https://w3c.github.io/trace-context-mqtt/) +> once those standards reach a stable state. + ### Span name The span name SHOULD be set to the message destination name and the operation being performed in the following format: