Rename CorrelationContext to Baggage (#857)

* Rename CorrelationContext to Baggage

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Update CHANGELOG.md

Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>

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))

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)

specification/baggage/api.md

@@ -0,0 +1,138 @@
+# Baggage API
+
+<details>
+<summary>
+Table of Contents
+</summary>
+
+- [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)
+
+</details>
+
+## 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).

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.
 

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:

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.

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)