Skip to content

Commit

Permalink
Context propagation to client instrumentation
Browse files Browse the repository at this point in the history 
Relates to open-telemetry#3811

Signed-off-by: Juraci Paixão Kröhling <juraci@kroehling.de>
  • Loading branch information
@jpkrohling
jpkrohling committed Jan 15, 2024
1 parent 12cd1b1 commit 457a27b
Show file tree
Hide file tree
Showing 6 changed files with 74 additions and 7 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ release.

### Context

- Context propagation to client instrumentation.
([#nnn](https://github.com/open-telemetry/opentelemetry-specification/pull/nnn))

### Traces

### Metrics
Expand Down
1 change: 1 addition & 0 deletions spec-compliance-matrix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
| Get current Context | | N/A| + | + | + | + | + | + | + | + | + | + |
| Composite Propagator | | + | + | + | + | + | + | + | + | + | + | + |
| Global Propagator | | + | + | + | + | + | + | + | + | + | + | + |
| [ClientPropagator](specification/context/api-propagators.md#client-propagator) | | - | - | - | - | - | - | - | - | - | - | - |
| TraceContext Propagator | | + | + | + | + | + | + | + | + | + | + | + |
| B3 Propagator | | + | + | + | + | + | + | + | + | + | + | + |
| Jaeger Propagator | | + | + | + | + | + | + | | + | + | - | + |
Expand Down
1 change: 1 addition & 0 deletions specification/configuration/file-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,7 @@ unset, Create fails fast since there is no default value for `exporter`.
* `MeterProvider`
* `LoggerProvider`
* `Propagators`
* `ClientPropagators`

The multiple responses MAY be returned using a tuple, or some other data
structure encapsulating the components.
Expand Down
1 change: 1 addition & 0 deletions specification/configuration/sdk-environment-variables.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service) resource attribute | | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. |
| OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | |
| OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a `Propagator` only once. |
| OTEL_CLIENT_PROPAGATORS | Client propagators to be used as a comma-separated list | | Values MUST be deduplicated in order to register a `ClientPropagator` only once. |
| OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See [Sampling](../trace/sdk.md#sampling) |
| OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the implementation MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. |

Expand Down
61 changes: 58 additions & 3 deletions specification/context/api-propagators.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,33 @@ interceptors and `Propagators`, where the interceptors detect incoming and outgo
The Propagators API is expected to be leveraged by users writing
instrumentation libraries.

## Propagator Classes

There are two classes of propagators:

* `Propagator`, or "forward propagator", which sends data forward to the next
in process in chain
* `ClientPropagator` (optional), a newer specialization of `Propagator`, which
sends trace context back to the caller.

The API is the same for both classes, but SDKs MUST NOT call `ClientPropagator`s
to propagate the context to the next process, and MUST NOT call `Propagator`s
when propagating the context back to the caller.

For historical reasons, whenever "Propagator" is used, a forward propagator is
implied.

### Client Propagator

While the classic context propagation was designed to carry values to the next
process in the chain of execution, there are cases where we want to send the
trace context back to the caller. For instance, when a client has made an
initial document request to a backend, the backend might have generated a trace
context. Once the client loads the document, it can record the timings and use
the same trace conterxt it got from the initial document headers. This trace
context might be used as a link to/from a new trace, or might be directly reused
as the parent of new spans.

## Propagator Types

A `Propagator` type defines the restrictions imposed by a specific transport
Expand Down Expand Up @@ -290,9 +317,13 @@ If the `TextMapPropagator`'s `Inject` implementation accepts the optional `Sette

The OpenTelemetry API MUST provide a way to obtain a propagator for each
supported `Propagator` type. Instrumentation libraries SHOULD call propagators
to extract and inject the context on all remote calls. Propagators, depending on
the language, MAY be set up using various dependency injection techniques or
available as global accessors.
to extract and inject the context on all outgoing remote calls. Propagators,
depending on the language, MAY be set up using various dependency injection
techniques or available as global accessors.

The OpenTelemetry API SHOULD provide similar facilities for `ClientPropagator`s,
and instrumentation libraries SHOULD call client propagators to inject the
context on the response to remote calls.

**Note:** It is a discouraged practice, but certain instrumentation libraries
might use proprietary context propagation protocols or be hardcoded to use a
Expand All @@ -312,6 +343,11 @@ propagators. If pre-configured, `Propagator`s SHOULD default to a composite
`Propagator` specified in the [Baggage API](../baggage/api.md#propagation).
These platforms MUST also allow pre-configured propagators to be disabled or overridden.

Platforms MUST NOT pre-configure `ClientPropagator`s, those should be explicitly
enabled by service owners in order to not leak unintended information to
callers, which might be untrusted clients, like web browsers over the public
internet.

### Get Global Propagator

This method MUST exist for each supported `Propagator` type.
Expand All @@ -328,6 +364,22 @@ Required parameters:

- A `Propagator`. This usually will be a composite instance.

### Get Global ClientPropagator

This method MUST exist for each supported `ClientPropagator` type.

Returns a global `ClientPropagator`. This usually will be composite instance.

### Set Global ClientPropagator

This method MUST exist for each supported `ClientPropagator` type.

Sets the global `ClientPropagator` instance.

Required parameters:

- A `ClientPropagator`. This usually will be a composite instance.

## Propagators Distribution

The official list of propagators that MUST be maintained by the OpenTelemetry
Expand Down Expand Up @@ -355,6 +407,9 @@ Additional `Propagator`s implementing vendor-specific protocols such as AWS
X-Ray trace header protocol MUST NOT be maintained or distributed as part of
the Core OpenTelemetry repositories.

At the moment, no `ClientPropagator`s are available. A candidate for the
near-future are W3C TraceContext's `traceresponse`.

### B3 Requirements

B3 has both single and multi-header encodings. It also has semantics that do not
Expand Down
14 changes: 10 additions & 4 deletions specification/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -349,13 +349,19 @@ See the [Context](context/README.md)

## Propagators

OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values
such as `Span`s (usually only the `SpanContext` portion) and `Baggage`. Different `Propagator` types define the restrictions
imposed by a specific transport and bound to a data type.
OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting
concern values such as `Span`s (usually only the `SpanContext` portion) and
`Baggage`. Different `Propagator` classes and types define the restrictions
imposed by a specific direction, transport, and are bound to a data type.

Propagators can be of one of two classes: `Propagator` (classic, forward), or
`ClientPropagator` (backward). See [Propagator
Classes](context/api-propagators.md#propagator-classes).

The Propagators API currently defines one `Propagator` type:

- `TextMapPropagator` injects values into and extracts values from carriers as text.
- `TextMapPropagator` injects values into and extracts values from carriers as
text.

## Collector

Expand Down

0 comments on commit 457a27b

Please sign in to comment.