From 691bd090777d411312abf00339776bb2ad4ea0c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Mon, 15 Jan 2024 14:22:56 +0100 Subject: [PATCH] Context propagation to client instrumentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Relates to #3811 Signed-off-by: Juraci Paixão Kröhling --- CHANGELOG.md | 3 + spec-compliance-matrix.md | 1 + .../configuration/file-configuration.md | 1 + .../sdk-environment-variables.md | 1 + specification/context/api-propagators.md | 61 ++++++++++++++++++- specification/overview.md | 14 +++-- 6 files changed, 74 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 38176c8bb62..8ce2fdd661e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. ### Context +- Context propagation to client instrumentation. + ([#nnn](https://github.com/open-telemetry/opentelemetry-specification/pull/nnn)) + ### Traces ### Metrics diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 10570f92fc6..3c72d942b86 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -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 | | + | + | + | + | + | + | | + | + | - | + | diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index b530ee73ab1..d56b4c6c060 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -290,6 +290,7 @@ Interpret [configuration model](#in-memory-configuration-model) and return SDK c * `MeterProvider` * `LoggerProvider` * `Propagators` +* `ClientPropagators` The multiple responses MAY be returned using a tuple, or some other data structure encapsulating the components. diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index ef4794cb046..7b48712de5a 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -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. | diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 762b309ef01..60f0e5c6c3b 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -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 @@ -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 @@ -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. @@ -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 @@ -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 diff --git a/specification/overview.md b/specification/overview.md index ca6ef858fdb..7f1307847de 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -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