Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make messaging context propagation requirements explicit #2750

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
60 changes: 60 additions & 0 deletions specification/trace/semantic_conventions/messaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,16 @@
<!-- toc -->

- [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)
Expand All @@ -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.
Expand All @@ -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
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is "settling" really the notification about the message to be processed?
In general, the intermediary is only interested to know that the message was delivered to the consumer so on "receiving" it should be settled.
Processing the message is part of the "contract" between producer and consumer, so that by using a request-reply pattern and a "reply-to" address/queue/topic, the consumer can notify (via a new message) to the producer that the processing happened.


### 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.
Expand Down Expand Up @@ -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
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
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
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
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:
Expand Down