Split context and propagation into seperate areas

spec-compliance-matrix.md

@@ -241,7 +241,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
 | Jaeger Propagator                                                                |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | -    | +     |
 | OT Propagator                                                                    |          | +  | +    | +  | +      |      |        |     |      |     |      |       |
 | OpenCensus Binary Propagator                                                     |          | +  |      |    |        |      |        |     |      |     |      |       |
-| [TextMapPropagator](specification/context/api-propagators.md#textmap-propagator) |          | +  | +    |    | +      | +    |        | +   |      | +   |      |       |
+| [TextMapPropagator](specification/propagators/api.md#textmap-propagator) |          | +  | +    |    | +      | +    |        | +   |      | +   |      |       |
 | Fields                                                                           |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | Setter argument                                                                  | X        | N/A| +    | +  | +      | +    | +      | +   | N/A  | +   | +    | +     |
 | Getter argument                                                                  | X        | N/A| +    | +  | +      | +    | +      | +   | N/A  | +   | +    | +     |

specification/README.md

@@ -27,13 +27,14 @@ path_base_for_github_subdir:
   - [Performance](performance.md)
 - API Specification
   - [Context](context/README.md)
-    - [Propagators](context/api-propagators.md)
     - [Environment Variable Carriers](context/env-carriers.md)
   - [Baggage](baggage/api.md)
   - [Tracing](trace/api.md)
   - [Metrics](metrics/api.md)
   - [Logs](logs/README.md)
     - [API](logs/api.md)
+  - [Propagators](propagators/README.md)
+    - [API](propagators/api.md)
 - SDK Specification
   - [Tracing](trace/sdk.md)
   - [Metrics](metrics/sdk.md)

specification/baggage/api.md

@@ -142,11 +142,11 @@ MUST provide the following functionality to interact with a `Context` instance:
 - Insert the `Baggage` to a `Context` instance
 
 The functionality listed above is necessary because API users SHOULD NOT have
-access to the [Context Key](../context/README.md#create-a-key) used by the
+access to the [Context Key](../context/api.md#create-a-key) used by the
 Baggage API implementation.
 
 If the language has support for implicitly propagated `Context` (see
-[here](../context/README.md#optional-global-operations)), the API SHOULD also
+[here](../context/api.md#global-operations-optional)), the API SHOULD also
 provide the following functionality:
 
 - Get the currently active `Baggage` from the implicit context. This is
@@ -180,7 +180,7 @@ The API layer or an extension package MUST include the following `Propagator`s:
 
 * A `TextMapPropagator` implementing the [W3C Baggage Specification][w3c].
 
-See [Propagators Distribution](../context/api-propagators.md#propagators-distribution)
+See [Propagators Distribution](../propagators/api.md#propagators-distribution)
 for how propagators are to be distributed.
 
 See [Environment Variable Carriers](../context/env-carriers.md) for how propagation should
@@ -193,7 +193,7 @@ to the optional metadata.
 On `extract`, the propagator should store all metadata as a single metadata instance per entry.
 On `inject`, the propagator should append the metadata per the W3C specification format.
 Refer to the API Propagators
-[Operation](../context/api-propagators.md#operations) section for the
+[Operation](../propagators/api.md#operations) section for the
 additional requirements these operations need to follow.
 
 ## Conflict Resolution

specification/compatibility/opencensus.md

@@ -45,12 +45,12 @@ Starting with an application using entirely OpenCensus instrumention for traces
     1. Install the OpenTelemetry SDK, with an equivalent exporter
         1. If using an OpenCensus exporter, switch to using an OTLP exporter
     2. Install equivalent OpenTelemetry resource detectors
-    3. Install OpenTelemetry [`W3c TraceContext`](../context/api-propagators.md#propagators-distribution) propagator, which is the equivalent of the OpenCensus' `TextFormat` propagator.
+    3. Install OpenTelemetry [`W3c TraceContext`](../propagators/api.md#propagators-distribution) propagator, which is the equivalent of the OpenCensus' `TextFormat` propagator.
     4. **breaking**: Install the metrics and trace bridges
     5. Remove initialization of OpenCensus exporters
 2. Migrate the instrumentation (API)
     1. **breaking**: For OpenCensus instrumentation packages, migrate to the OpenTelemetry equivalent.
-        1. If migrating gRPC, enable the [`BinaryPropagation`](../context/api-propagators.md#propagators-distribution) propagator if the language supports it. Otherwise, enable OpenCensus `BinaryPropagation` on the OpenTelemetry gRPC instrumentation.
+        1. If migrating gRPC, enable the [`BinaryPropagation`](../propagators/api.md#propagators-distribution) propagator if the language supports it. Otherwise, enable OpenCensus `BinaryPropagation` on the OpenTelemetry gRPC instrumentation.
     2. For external dependencies, wait for it to migrate to OpenTelemetry, and update the dependency.
     3. For instrumentation which is part of the application, migrate it following the "library" guidance below.
 3. Clean up: Remove the metrics and trace bridges
@@ -203,7 +203,7 @@ This adapter MUST provide an implementation of OpenCensus `BinaryPropogator` to
 write OpenCensus binary format using OpenTelemetry's context.  This
 implementation may be drawn from OpenCensus if applicable.
 
-The `BinaryPropagator` MUST be a [TextMapPropagator](../context/api-propagators.md#textmap-propagator)
+The `BinaryPropagator` MUST be a [TextMapPropagator](../propagators/api.md#textmap-propagator)
 if possible in the language. Otherwise, the `BinaryPropagator` MUST be a library,
 which is expected to be used by OpenTelemetry gRPC instrumentation. gRPC
 instrumentation in those languages SHOULD NOT enable the `BinaryPropagator` by

specification/configuration/sdk-environment-variables.md

@@ -183,8 +183,8 @@ Known values for `OTEL_PROPAGATORS` are:
 
 - `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context/)
 - `"baggage"`: [W3C Baggage](https://www.w3.org/TR/baggage/)
-- `"b3"`: [B3 Single](../context/api-propagators.md#configuration)
-- `"b3multi"`: [B3 Multi](../context/api-propagators.md#configuration)
+- `"b3"`: [B3 Single](../propagators/api.md#configuration)
+- `"b3multi"`: [B3 Multi](../propagators/api.md#configuration)
 - `"jaeger"`: [Jaeger](https://www.jaegertracing.io/sdk-migration/#propagation-format)
 - `"xray"`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) (_third party_)
 - `"ottrace"`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=) (_third party_)

specification/configuration/sdk.md

@@ -134,7 +134,7 @@ interfaces in the configuration data model:
 | SDK extension plugin interface                                                              | Status                                                                             |
 |---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
 | [resource detector](../resource/sdk.md#detecting-resource-information-from-the-environment) | +                                                                                  |
-| [text map propagator](../context/api-propagators.md#textmap-propagator)                     | +                                                                                  |
+| [text map propagator](../propagators/api.md#textmap-propagator)                     | +                                                                                  |
 | [span exporter](../trace/sdk.md#span-exporter)                                              | +                                                                                  |
 | [span processor](../trace/sdk.md#span-processor)                                            | +                                                                                  |
 | [sampler](../trace/sdk.md#sampler)                                                          | +                                                                                  |
@@ -249,7 +249,7 @@ Interpret configuration model and return SDK components.
 * [TracerProvider](../trace/sdk.md#tracer-provider)
 * [MeterProvider](../metrics/sdk.md#meterprovider)
 * [LoggerProvider](../logs/sdk.md#loggerprovider)
-* [Propagators](../context/api-propagators.md#composite-propagator)
+* [Propagators](../propagators/api.md#composite-propagator)
 * [ConfigProvider](#configprovider)
 
 The multiple responses MAY be returned using a tuple, or some other data

specification/context/README.md

@@ -9,23 +9,7 @@ path_base_for_github_subdir:
 
 **Status**: [Stable](../document-status.md).
 
-<details>
-<summary>Table of Contents</summary>
-
-<!-- toc -->
-
-- [Overview](#overview)
-- [Create a key](#create-a-key)
-- [Get value](#get-value)
-- [Set value](#set-value)
-- [Optional Global operations](#optional-global-operations)
-  * [Get current Context](#get-current-context)
-  * [Attach Context](#attach-context)
-  * [Detach Context](#detach-context)
-
-<!-- tocstop -->
-
-</details>
+**Concept**: [Context](https://opentelemetry.io/docs/concepts/context-propagation/#context)
 
 ## Overview
 
@@ -49,88 +33,3 @@ 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 baggage entries for a specified
 `Context`.
-
-A `Context` is expected to have the following operations, with their
-respective language differences:
-
-## Create a key
-
-Keys are used to allow cross-cutting concerns to control access to their local state.
-They are unique such that other libraries which may use the same context
-cannot accidentally use the same key. It is recommended that concerns mediate
-data access via an API, rather than provide direct public access to their keys.
-
-The API MUST accept the following parameter:
-
-- The key name. The key name exists for debugging purposes and does not uniquely identify the key. Multiple calls to `CreateKey` with the same name SHOULD NOT return the same value unless language constraints dictate otherwise. Different languages may impose different restrictions on the expected types, so this parameter remains an implementation detail.
-
-The API MUST return an opaque object representing the newly created key.
-
-## Get value
-
-Concerns can access their local state in the current execution state
-represented by a `Context`.
-
-The API MUST accept the following parameters:
-
-- The `Context`.
-- The key.
-
-The API MUST return the value in the `Context` for the specified key.
-
-## Set value
-
-Concerns can record their local state in the current execution state
-represented by a `Context`.
-
-The API MUST accept the following parameters:
-
-- The `Context`.
-- The key.
-- The value to be set.
-
-The API MUST return a new `Context` containing the new value.
-
-## Optional Global operations
-
-These operations are expected to only be implemented by languages
-using `Context` implicitly, and thus are optional. These operations
-SHOULD only be used to implement automatic scope switching and define
-higher level APIs by SDK components and OpenTelemetry instrumentation libraries.
-
-### Get current Context
-
-The API MUST return the `Context` associated with the caller's current execution unit.
-
-### Attach Context
-
-Associates a `Context` with the caller's current execution unit.
-
-The API MUST accept the following parameters:
-
-- The `Context`.
-
-The API MUST return a value that can be used as a `Token` to restore the previous
-`Context`.
-
-Note that every call to this operation should result in a corresponding call to
-[Detach Context](#detach-context).
-
-### Detach Context
-
-Resets the `Context` associated with the caller's current execution unit
-to the value it had before attaching a specified `Context`.
-
-This operation is intended to help making sure the correct `Context`
-is associated with the caller's current execution unit. Users can
-rely on it to identify a wrong call order, i.e. trying to detach
-a `Context` that is not the current instance. In this case the operation
-can emit a signal to warn users of the wrong call order, such as logging
-an error or returning an error value.
-
-The API MUST accept the following parameters:
-
-- A `Token` that was returned by a previous call to attach a `Context`.
-
-The API MAY return a value used to check whether the operation
-was successful or not.

specification/context/api.md

@@ -0,0 +1,95 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: API
+weight: 1
+--->
+
+# Context API
+
+**Status**: [Stable](../document-status.md).
+
+## Operations
+
+A `Context` is expected to have the following operations, with their
+respective language differences:
+
+### Create a key
+
+Keys are used to allow cross-cutting concerns to control access to their local state.
+They are unique such that other libraries which may use the same context
+cannot accidentally use the same key. It is recommended that concerns mediate
+data access via an API, rather than provide direct public access to their keys.
+
+The API MUST accept the following parameter:
+
+- The key name. The key name exists for debugging purposes and does not uniquely identify the key. Multiple calls to `CreateKey` with the same name SHOULD NOT return the same value unless language constraints dictate otherwise. Different languages may impose different restrictions on the expected types, so this parameter remains an implementation detail.
+
+The API MUST return an opaque object representing the newly created key.
+
+### Get value
+
+Concerns can access their local state in the current execution state
+represented by a `Context`.
+
+The API MUST accept the following parameters:
+
+- The `Context`.
+- The key.
+
+The API MUST return the value in the `Context` for the specified key.
+
+### Set value
+
+Concerns can record their local state in the current execution state
+represented by a `Context`.
+
+The API MUST accept the following parameters:
+
+- The `Context`.
+- The key.
+- The value to be set.
+
+The API MUST return a new `Context` containing the new value.
+
+## Global Operations [Optional]
+
+These operations are expected to only be implemented by languages
+using `Context` implicitly, and thus are optional. These operations
+SHOULD only be used to implement automatic scope switching and define
+higher level APIs by SDK components and OpenTelemetry instrumentation libraries.
+
+### Get current Context
+
+The API MUST return the `Context` associated with the caller's current execution unit.
+
+### Attach Context
+
+Associates a `Context` with the caller's current execution unit.
+
+The API MUST accept the following parameters:
+
+- The `Context`.
+
+The API MUST return a value that can be used as a `Token` to restore the previous
+`Context`.
+
+Note that every call to this operation should result in a corresponding call to
+[Detach Context](#detach-context).
+
+### Detach Context
+
+Resets the `Context` associated with the caller's current execution unit
+to the value it had before attaching a specified `Context`.
+
+This operation is intended to help making sure the correct `Context`
+is associated with the caller's current execution unit. Users can
+rely on it to identify a wrong call order, i.e. trying to detach
+a `Context` that is not the current instance. In this case the operation
+can emit a signal to warn users of the wrong call order, such as logging
+an error or returning an error value.
+
+The API MUST accept the following parameters:
+
+- A `Token` that was returned by a previous call to attach a `Context`.
+
+The API MAY return a value used to check whether the operation
+was successful or not.

specification/context/env-carriers.md

@@ -32,9 +32,9 @@
 
 Environment variables provide a mechanism to propagate context and baggage
 information across process boundaries when network protocols are not
-applicable. This specification extends the [API Propagators](../context/api-propagators.md)
+applicable. This specification extends the [API Propagators](../propagators/api.md)
 to define how the
-[TextMapPropagator](../context/api-propagators.md#textmap-propagator) can be
+[TextMapPropagator](../propagators/api.md#textmap-propagator) can be
 used with environment variables.
 
 Common systems where context propagation via environment variables is useful
@@ -49,7 +49,7 @@ include:
 Propagating context via environment variables involves reading and writing to
 environment variables. A `TextMapPropagator` SHOULD be used alongside its
 normal `Get`, `Set`, `Extract`, and `Inject` functionality as described in the [API
-Propagators](../context/api-propagators.md) specification.
+Propagators](../propagators/api.md) specification.
 
 ### Environment Variable Names
 

specification/propagators/README.md

@@ -0,0 +1,43 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Propagators
+
+**Status**: [Stable](../document-status.md)
+
+**Concept**: [Propagation](https://opentelemetry.io/docs/concepts/context-propagation/#propagation)
+
+## Overview
+
+Cross-cutting concerns send their state to the next process using
+`Propagator`s, which are defined as objects used to read and write
+context data to and from messages exchanged by the applications.
+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 `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.
+
+The Propagators API is expected to be leveraged by users writing
+instrumentation libraries.
+
+## Propagator Types
+
+A `Propagator` type defines the restrictions imposed by a specific transport
+and is bound to a data type, in order to propagate in-band context data across process boundaries.
+
+The Propagators API currently defines one `Propagator` type:
+
+- `TextMapPropagator` is a type that injects values into and extracts values
+  from carriers as string key/value pairs.
+
+### Carrier
+
+A carrier is the medium used by `Propagator`s to read values from and write values to.
+Each specific `Propagator` type defines its expected carrier type, such as a string map
+or a byte array.
+
+Carriers used at [Inject](api.md#inject) are expected to be mutable.