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 1 commit
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 @@ -70,6 +70,8 @@ release.
([#2675](https://github.com/open-telemetry/opentelemetry-specification/pull/2675))
- Add OpenSearch to db.system semantic conventions
([#2718](https://github.com/open-telemetry/opentelemetry-specification/pull/2718)).
- Make context propagation requirements explict for messaging semantic conventions
([#xyz](https://github.com/open-telemetry/opentelemetry-specification/pull/xyz)).

### Compatibility

Expand Down
41 changes: 41 additions & 0 deletions specification/trace/semantic_conventions/messaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
* [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 Down Expand Up @@ -80,6 +81,46 @@ 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.

Due to the complex nature of messaging systems, it cannot be assumed
that all components are instrumented and propagate context accordingly.
For example, an application using a messaging system offered via
software as a service (SaaS) that does not propagate context will lead to incomplete traces.

To be able to correlate consumer traces with producer traces without requiring
intermediary instrumentation, the context needs to be propagated on a
*per-message* basis instead of on a *per-request* basis. This allows all components
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
to have access to the same per-message context information, making it possible
to correlate all stages involved in processing a message with the message's
creation.
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved

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 to 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.
The message creation context SHOULD be attached in such a way that it is
not possible to be changed by intermediaries.
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved

> 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