diff --git a/CHANGELOG.md b/CHANGELOG.md index 43844b3453f..2ce2f2ac592 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ New: Updates: +- Renamed `CorrelationContext` to `Baggage`: + ([#857](https://github.com/open-telemetry/opentelemetry-specification/pull/857)) - Add semantic convention for NGINX custom HTTP 499 status code. - Adapt semantic conventions for the span name of messaging systems ([#690](https://github.com/open-telemetry/opentelemetry-specification/pull/690)) diff --git a/README.md b/README.md index 2c741071259..a62ed7e87dd 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ The OpenTelemetry specification describes the cross-language requirements and ex - [Library Guidelines](specification/library-guidelines.md) - [Package/Library Layout](specification/library-layout.md) - API Specification - - [CorrelationContext](specification/correlationcontext/api.md) + - [Baggage](specification/baggage/api.md) - [Propagators](specification/context/api-propagators.md) - [Tracing](specification/trace/api.md) - [Metrics](specification/metrics/api.md) diff --git a/specification/baggage/api.md b/specification/baggage/api.md new file mode 100644 index 00000000000..3547da757b9 --- /dev/null +++ b/specification/baggage/api.md @@ -0,0 +1,138 @@ +# Baggage API + +
+ +Table of Contents + + +- [Overview](#overview) + - [Baggage](#baggage) + - [Get baggages](#get-all) + - [Get baggage](#get-baggage) + - [Set baggage](#set-baggage) + - [Remove baggage](#remove-baggage) + - [Clear](#clear) +- [Baggage Propagation](#baggage-propagation) + - [Serialization](#serialization) +- [Conflict Resolution](#conflict-resolution) + +
+ +## Overview + +The Baggage API consists of: + +- the `Baggage` +- functions to interact with the `Baggage` in a `Context` + +### Baggage + +`Baggage` is used to annotate telemetry, adding context and information to metrics, traces, and logs. +It is an abstract data type represented by a set of name/value pairs describing user-defined properties. +Each name in `Baggage` MUST be associated with exactly one value. + +### Get all + +Returns the name/value pairs in the `Baggage`. The order of name/value pairs MUST NOT be +significant. Based on the language specification, the returned value can be +either an immutable collection or an immutable iterator to the collection of +name/value pairs in the `Baggage`. + +OPTIONAL parameters: + +`Context` the context containing the `Baggage` from which to get the baggages. + +### Get baggage + +To access the value for a name/value pair by a prior event, the Baggage API +SHALL provide a function that takes a context and a name as input, and returns a +value. Returns the value associated with the given name, or null +if the given name is not present. + +REQUIRED parameters: + +`Name` the name to return the value for. + +OPTIONAL parameters: + +`Context` the context containing the `Baggage` from which to get the baggage entry. + +### Set baggage + +To record the value for a name/value pair, the Baggage API SHALL provide a function which +takes a context, a name, and a value as input. Returns a new `Context` which +contains a `Baggage` with the new value. + +REQUIRED parameters: + +`Name` the name for which to set the value. + +`Value` the value to set. + +OPTIONAL parameters: + +`Context` the context containing the `Baggage` in which to set the baggage entry. + +### Remove baggage + +To delete a name/value pair, the Baggage API SHALL provide a function which takes a context +and a name as input. Returns a new `Context` which no longer contains the selected name. + +REQUIRED parameters: + +`Name` the name to remove. + +OPTIONAL parameters: + +`Context` the context containing the `Baggage` from which to remove the baggage entry. + +### Clear + +To avoid sending any name/value pairs to an untrusted process, the Baggage API SHALL provide +a function to remove all baggage entries from a context. Returns a new `Context` +with no `Baggage`. + +OPTIONAL parameters: + +`Context` the context containing the `Baggage` from which to remove all baggage entries. + +## Baggage Propagation + +`Baggage` MAY be propagated across process boundaries or across any arbitrary boundaries +(process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons. + +### Serialization + +Until the [W3C Baggage](https://w3c.github.io/baggage/) specification is recommended for use, OpenTelemetry `Baggage` implementations MUST be serialized according to the [editor's draft of W3C Correlation Context as of March 27, 2020](https://github.com/w3c/correlation-context/blob/c974664b9ab4d33af6355f1f7f03a2d52c89a99e/correlation_context/HTTP_HEADER_FORMAT.md) using a vendor-specific header name to avoid collisions with the W3C Baggage specification should it change in the future. + +#### Header Name + +`Baggage` implementations MUST use the header name `otcorrelations`. + +#### Header Value + +`Baggage` MUST be serialized according to the [editor's draft of W3C Correlation Context as of March 27, 2020](https://github.com/w3c/correlation-context/blob/c974664b9ab4d33af6355f1f7f03a2d52c89a99e/correlation_context/HTTP_HEADER_FORMAT.md). + +`Baggage` values MUST be serialized as Percent-Encoded UTF-8 strings according to [RFC 3986 Section 2.1](https://tools.ietf.org/html/rfc3986#section-2.1). + +#### Example + +Baggage: + +```json +{ + "user": "foo@example.com", + "name": "Example Name" +} +``` + +Header: + +``` +otbaggages: user=foo%40example.com,name=Example%20Name +``` + +## Conflict Resolution + +If a new name/value pair is added and its name is the same as an existing name, than the new pair MUST take precedence. The value +is replaced with the added value (regardless if it is locally generated or received from a remote peer). diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index e00124b49f2..654dd21e88c 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -35,7 +35,7 @@ Each concern creates a set of `Propagator`s for every supported `Propagator` type. `Propagator`s leverage the `Context` to inject and extract data for each -cross-cutting concern, such as traces and correlation context. +cross-cutting concern, such as traces and `Baggage`. Propagation is usually implemented via a cooperation of library-specific request interceptors and `Propagators`, where the interceptors detect incoming and outgoing requests and use the `Propagator`'s extract and inject operations respectively. @@ -76,7 +76,7 @@ Injects the value into a carrier. For example, into the headers of an HTTP reque Required arguments: - A `Context`. The Propagator MUST retrieve the appropriate value from the `Context` first, such as -`SpanContext`, `CorrelationContext` or another cross-cutting concern context. +`SpanContext`, `Baggage` or another cross-cutting concern context. - The carrier that holds the propagation fields. For example, an outgoing message or HTTP request. #### Extract @@ -94,7 +94,7 @@ Required arguments: Returns a new `Context` derived from the `Context` passed as argument, containing the extracted value, which can be a `SpanContext`, -`CorrelationContext` or another cross-cutting concern context. +`Baggage` or another cross-cutting concern context. ## TextMap Propagator @@ -271,8 +271,8 @@ Implementations MAY provide global `Propagator`s for each supported `Propagator` type. If offered, the global `Propagator`s should default to a composite `Propagator` -containing the W3C Trace Context Propagator and the Correlation Context `Propagator` -specified in [api-correlationcontext.md](../correlationcontext/api.md#serialization), +containing the W3C Trace Context Propagator and the Baggage `Propagator` +specified in [api-baggage.md](../baggage/api.md#serialization), in order to provide propagation even in the presence of no-op OpenTelemetry implementations. diff --git a/specification/context/context.md b/specification/context/context.md index 21074479c9c..7824713ce7c 100644 --- a/specification/context/context.md +++ b/specification/context/context.md @@ -36,8 +36,8 @@ or implicit. Users writing instrumentation in languages that use `Context` implicitly are discouraged from using the `Context` API directly. In those cases, users will manipulate `Context` through cross-cutting concerns APIs instead, in order to -perform operations such as setting trace or correlation context values for -a specified `Context`. +perform operations such as setting trace or baggage entries for a specified +`Context`. A `Context` is expected to have the following operations, with their respective language differences: diff --git a/specification/correlationcontext/api.md b/specification/correlationcontext/api.md deleted file mode 100644 index 3833620b461..00000000000 --- a/specification/correlationcontext/api.md +++ /dev/null @@ -1,138 +0,0 @@ -# Correlations API - -
- -Table of Contents - - -- [Overview](#overview) - - [CorrelationContext](#correlationcontext) - - [Get correlations](#get-correlations) - - [Get correlation](#get-correlation) - - [Set correlation](#set-correlation) - - [Remove correlation](#remove-correlation) - - [Clear correlations](#clear-correlations) -- [CorrelationContext Propagation](#correlationcontext-propagation) - - [Serialization](#serialization) -- [Conflict Resolution](#conflict-resolution) - -
- -## Overview - -The Correlations API consists of: - -- the `CorrelationContext` -- functions to interact with the `CorrelationContext` in a `Context` - -### CorrelationContext - -`CorrelationContext` is used to annotate telemetry, adding context and information to metrics, traces, and logs. -It is an abstract data type represented by a set of name/value pairs describing user-defined properties. -Each name in `CorrelationContext` MUST be associated with exactly one value. - -### Get correlations - -Returns the name/value pairs in the `CorrelationContext`. The order of name/value pairs MUST NOT be -significant. Based on the language specification, the returned value can be -either an immutable collection or an immutable iterator to the collection of -name/value pairs in the `CorrelationContext`. - -OPTIONAL parameters: - -`Context` the context containing the `CorrelationContext` from which to get the correlations. - -### Get correlation - -To access the value for a name/value pair by a prior event, the Correlations API -SHALL provide a function that takes a context and a name as input, and returns a -value. Returns the value associated with the given name, or null -if the given name is not present. - -REQUIRED parameters: - -`Name` the name to return the value for. - -OPTIONAL parameters: - -`Context` the context containing the `CorrelationContext` from which to get the correlation. - -### Set correlation - -To record the value for a name/value pair, the Correlations API SHALL provide a function which -takes a context, a name, and a value as input. Returns a new `Context` which -contains a `CorrelationContext` with the new value. - -REQUIRED parameters: - -`Name` the name for which to set the value. - -`Value` the value to set. - -OPTIONAL parameters: - -`Context` the context containing the `CorrelationContext` in which to set the correlation. - -### Remove correlation - -To delete a name/value pair, the Correlations API SHALL provide a function which takes a context -and a name as input. Returns a new `Context` which no longer contains the selected name. - -REQUIRED parameters: - -`Name` the name to remove. - -OPTIONAL parameters: - -`Context` the context containing the `CorrelationContext` from which to remove the correlation. - -### Clear correlations - -To avoid sending any name/value pairs to an untrusted process, the Correlations API SHALL provide -a function to remove all Correlations from a context. Returns a new `Context` -with no correlations. - -OPTIONAL parameters: - -`Context` the context containing the `CorrelationContext` from which to remove all correlations. - -## CorrelationContext Propagation - -`CorrelationContext` MAY be propagated across process boundaries or across any arbitrary boundaries -(process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons. - -### Serialization - -Until the [W3C Correlation Context](https://w3c.github.io/baggage/) specification is recommended for use, OpenTelemetry `CorrelationContext` implementations MUST be serialized according to the [editor's draft of W3C Correlation Context as of March 27, 2020](https://github.com/w3c/correlation-context/blob/c974664b9ab4d33af6355f1f7f03a2d52c89a99e/correlation_context/HTTP_HEADER_FORMAT.md) using a vendor-specific header name to avoid collisions with the W3C Correlation Context specification should it change in the future. - -#### Header Name - -`CorrelationContext` implementations MUST use the header name `otcorrelations`. - -#### Header Value - -`CorrelationContext` MUST be serialized according to the [editor's draft of W3C Correlation Context as of March 27, 2020](https://github.com/w3c/correlation-context/blob/c974664b9ab4d33af6355f1f7f03a2d52c89a99e/correlation_context/HTTP_HEADER_FORMAT.md). - -`CorrelationContext` values MUST be serialized as Percent-Encoded UTF-8 strings according to [RFC 3986 Section 2.1](https://tools.ietf.org/html/rfc3986#section-2.1). - -#### Example - -Correlation Context: - -```json -{ - "user": "foo@example.com", - "name": "Example Name" -} -``` - -Header: - -``` -otcorrelations: user=foo%40example.com,name=Example%20Name -``` - -## Conflict Resolution - -If a new name/value pair is added and its name is the same as an existing name, than the new pair MUST take precedence. The value -is replaced with the added value (regardless if it is locally generated or received from a remote peer). diff --git a/specification/glossary.md b/specification/glossary.md index ae127639c26..1ec28d4fe97 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -37,7 +37,7 @@ Some other fundamental terms are documented in the [overview document](overview. In OpenTelemetry we refer to **in-band data** as data that is passed between components of a distributed system as part of business messages, -for example, when trace or correlation contexts are included +for example, when trace or baggages are included in the HTTP requests in the form of HTTP headers. Such data usually does not contain the telemetry, but is used to correlate and join the telemetry produced by various components. diff --git a/specification/library-layout.md b/specification/library-layout.md index 34bca2c6749..2fb0fc4ed24 100644 --- a/specification/library-layout.md +++ b/specification/library-layout.md @@ -17,7 +17,7 @@ api ├── metrics ├── trace │ └── propagation - ├── correlationcontext + ├── baggage │ └── propagation ├── internal └── logs @@ -33,9 +33,9 @@ This directory describes the API that provides in-process context propagation. This directory describes the Metrics API that can be used to record application metrics. -### [/correlationcontext](correlationcontext/api.md) +### [/baggage](baggage/api.md) -This directory describes the CorrelationContext API that can be used to manage context propagation +This directory describes the Baggage API that can be used to manage context propagation and metrics-related labeling. ### [/trace](trace/api.md) @@ -66,7 +66,7 @@ sdk ├── metrics ├── resource ├── trace - ├── correlationcontext + ├── baggage ├── internal └── logs ``` @@ -88,7 +88,7 @@ information about the entity for which stats or traces are recorded. For example by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name. -### `/sdk/correlationcontext` +### `/sdk/baggage` ### [/sdk/trace](trace/sdk.md) diff --git a/specification/logs/overview.md b/specification/logs/overview.md index 859a00d024b..52e4455669e 100644 --- a/specification/logs/overview.md +++ b/specification/logs/overview.md @@ -65,7 +65,7 @@ Distributed tracing introduced the notion of request context propagation. Fundamentally, though, nothing prevents the logs to adopt the same context propagation concepts. If the recorded logs contained request context identifiers -(such as trace and span ids or user-defined correlation context) it would result +(such as trace and span ids or user-defined baggage) it would result in much richer correlation between logs and traces, as well as correlation between logs emitted by different components of a distributed system. This would make logs significantly more valuable in distributed systems. diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 69d51e85ffd..d278d109be0 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -39,7 +39,7 @@ + [Direct instrument calling convention](#direct-instrument-calling-convention) + [RecordBatch calling convention](#recordbatch-calling-convention) * [Association with distributed context](#association-with-distributed-context) - + [Correlation context into metric labels](#correlation-context-into-metric-labels) + + [Baggage into metric labels](#baggage-into-metric-labels) - [Asynchronous instrument details](#asynchronous-instrument-details) * [Asynchronous calling conventions](#asynchronous-calling-conventions) + [Single-instrument observer](#single-instrument-observer) @@ -148,7 +148,7 @@ which is the user-facing entry point to the SDK. Instruments are classified in several ways that distinguish them from one another. -1. Synchronicity: A synchronous instrument is called by the user in a distributed [Context](../context/context.md) (i.e., Span context, Correlation context). An asynchronous instrument is called by the SDK once per collection interval, lacking a Context. +1. Synchronicity: A synchronous instrument is called by the user in a distributed [Context](../context/context.md) (i.e., Span context, Baggage). An asynchronous instrument is called by the SDK once per collection interval, lacking a Context. 2. Additivity: An additive instrument is one that records additive measurements, as described above. 3. Monotonicity: A monotonic instrument is an additive instrument, where the progression of each sum is non-decreasing. Monotonic instruments are useful for monitoring rate information. @@ -165,7 +165,7 @@ are synchronous, additive, and/or monotonic. | ValueObserver | No | No | No | The synchronous instruments are useful for measurements that are -gathered in a distributed [Context](../context/context.md) (i.e., Span context, Correlation context). The asynchronous instruments are +gathered in a distributed [Context](../context/context.md) (i.e., Span context, Baggage). The asynchronous instruments are useful when measurements are expensive, therefore should be gathered periodically. Read more [characteristics of synchronous and asynchronous instruments](#synchronous-and-asynchronous-instruments-compared) below. @@ -321,7 +321,7 @@ consist of: - [resources](../resource/sdk.md) associated with the SDK at startup. Synchronous events have one additional property, the distributed -[Context](../context/context.md) (i.e., Span context, Correlation context) +[Context](../context/context.md) (i.e., Span context, Baggage) that was active at the time. ## Meter provider @@ -419,7 +419,7 @@ libraries may be written to generate this metric. ### Synchronous and asynchronous instruments compared Synchronous instruments are called inside a request, meaning they -have an associated distributed [Context](../context/context.md) (i.e., Span context, Correlation context). Multiple metric events may occur for a +have an associated distributed [Context](../context/context.md) (i.e., Span context, Baggage). Multiple metric events may occur for a synchronous instrument within a given collection interval. Asynchronous instruments are reported by a callback, once per @@ -942,25 +942,25 @@ convention. Synchronous measurements are implicitly associated with the distributed [Context](../context/context.md) at runtime, which may -include a Span context and Correlation values. The Metric SDK may use +include a Span context and Baggage entries. The Metric SDK may use this information in many ways, but one feature is of particular interest in OpenTelemetry. -#### Correlation context into metric labels +#### Baggage into metric labels -Correlation context is supported in OpenTelemetry as a means for +Baggage is supported in OpenTelemetry as a means for labels to propagate from one process to another in a distributed computation. Sometimes it is useful to aggregate metric data using -distributed correlation values as metric labels. +distributed baggage entries as metric labels. -The use of correlation context must be explicitly configured, using +The use of Baggage must be explicitly configured, using the [Views API (WIP)](https://github.com/open-telemetry/oteps/pull/89) -to select specific key correlation values that should be applied as -labels. The default SDK will not automatically use correlation -context labels in the export pipeline, since using correlation labels +to select specific key baggage entries that should be applied as +labels. The default SDK will not automatically use Baggage +labels in the export pipeline, since using Baggage labels can be a significant expense. -Configuring views for applying Correlation context labels is a [work in +Configuring views for applying Baggage labels is a [work in progress](https://github.com/open-telemetry/oteps/pull/89). ## Asynchronous instrument details diff --git a/specification/overview.md b/specification/overview.md index f4cd0bce1b5..b3576ac1268 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -21,7 +21,7 @@ Table of Contents * [Metrics data model and SDK](#metrics-data-model-and-sdk) - [Logs](#logs) * [Data model](#data-model) -- [CorrelationContext](#correlationcontext) +- [Baggage](#baggage) - [Resources](#resources) - [Context Propagation](#context-propagation) - [Propagators](#propagators) @@ -231,24 +231,24 @@ from the backend. [Log Data Model](logs/data-model.md) defines how logs and events are understood by OpenTelemetry. -## CorrelationContext +## Baggage In addition to trace propagation, OpenTelemetry provides a simple mechanism for propagating -name/value pairs, called `CorrelationContext`. `CorrelationContext` is intended for +name/value pairs, called `Baggage`. `Baggage` is intended for indexing observability events in one service with attributes provided by a prior service in the same transaction. This helps to establish a causal relationship between these events. -While `CorrelationContext` can be used to prototype other cross-cutting concerns, this mechanism is primarily intended +While `Baggage` can be used to prototype other cross-cutting concerns, this mechanism is primarily intended to convey values for the OpenTelemetry observability systems. -These values can be consumed from `CorrelationContext` and used as additional dimensions for metrics, +These values can be consumed from `Baggage` and used as additional dimensions for metrics, or additional context for logs and traces. Some examples: - a web service can benefit from including context around what service has sent the request - a SaaS provider can include context about the API user or token that is responsible for that request - determining that a particular browser version is associated with a failure in an image processing service -For backward compatibility with OpenTracing, Baggage is propagated as `CorrelationContext` when +For backward compatibility with OpenTracing, Baggage is propagated as `Baggage` when using the OpenTracing bridge. New concerns with different criteria should consider creating a new cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but use a new HTTP header to convey data throughout a distributed trace. @@ -280,7 +280,7 @@ See the [Context](context/context.md) ## Propagators OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values -such as `SpanContext` and `CorrelationContext`. Different `Propagator` types define the restrictions +such as `SpanContext` and `Baggage`. Different `Propagator` types define the restrictions imposed by a specific transport and bound to a data type. The Propagators API currently defines one `Propagator` type: diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index c2f54f0affb..6a6b6f1c084 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -8,7 +8,7 @@ The goal of this specification is to unify the environment variable names betwee | ------------------------ | ------------------------------------------------- | --------------------------------- | ----------------------------------- | | OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | | See [Resource SDK](./resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | | OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | | -| OTEL_PROPAGATORS | Propagators to be used as a comma separated list | "tracecontext,correlationcontext" | | +| OTEL_PROPAGATORS | Propagators to be used as a comma separated list | "tracecontext,baggage" | | ## Batch Span Processor diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index dc1bc8af968..dcb76bc06e5 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -98,7 +98,7 @@ These attributes may be used for any operation with an authenticated and/or auth These attributes describe the authenticated user driving the user agent making requests to the instrumented system. It is expected this information would be propagated unchanged from node-to-node within the system -using the Correlation Context mechanism. These attributes should not be used to record system-to-system +using the Baggage mechanism. These attributes should not be used to record system-to-system authentication attributes. Examples of where the `enduser.id` value is extracted from: