Initial composite/global Propagators update for OTEP 66. (#440)

* Initial Propagators update for OTEP 66.

* Fix style.

* Initial feedback pass.

* Update specification/api-propagators.md

Co-Authored-By: Tyler Yahn <[email protected]>

* Update specification/api-propagators.md

Co-Authored-By: Tyler Yahn <[email protected]>

* Update specification/api-propagators.md

Co-Authored-By: Tyler Yahn <[email protected]>

* Update specification/api-propagators.md

Co-Authored-By: Tyler Yahn <[email protected]>

* Update specification/api-propagators.md

Co-Authored-By: Armin Ruech <[email protected]>

* Fix the mixed up getter/setter.

* Update specification/api-propagators.md

Co-Authored-By: Armin Ruech <[email protected]>

* Update specification/api-propagators.md

Co-Authored-By: Armin Ruech <[email protected]>

* Do not use RPC in api-propagators

* Use Format instead of format.

* Clarification on format in overview.md

Co-authored-by: Tyler Yahn <[email protected]>
Co-authored-by: Armin Ruech <[email protected]>

specification/api-propagators.md

@@ -5,6 +5,7 @@
 Table of Contents
 </summary>
 
+- [Overview](#overview)
 - [HTTP Text Format](#http-text-format)
  - [Fields](#fields)
  - [Inject](#inject)
@@ -13,22 +14,34 @@ Table of Contents
  - [Extract](#extract)
  - [Getter argument](#getter)
  - [Get](#get)
+- [Composite Propagator](#composite-propagator)
+- [Global Propagators](#global-propagators)
 
 </details>
 
-Propagators API currently consists of one format:
+## 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 `Format`.
+
+The Propagators API is expected to be leveraged by users writing
+instrumentation libraries.
+
+Propagators API currently consists of one `Format`:
 
 - `HTTPTextFormat` is used to inject and extract a value as text into carriers that travel
  in-band across process boundaries.
 
 Deserializing must set `IsRemote` to true on the returned `SpanContext`.
 
-A binary format will be added in the future.
+A binary `Format` will be added in the future.
 
 ## HTTP Text Format
 
-`HTTPTextFormat` is a formatter that injects and extracts a value as text into carriers that
-travel in-band across process boundaries.
+`HTTPTextFormat` is a formatter that injects and extracts a cross-cutting concern
+value as text into carriers that travel in-band across process boundaries.
 
 Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as
 RPC/HTTP request headers.
@@ -62,7 +75,7 @@ Injects the value downstream. For example, as http headers.
 
 Required arguments:
 
-- the value to be injected, can be `SpanContext` or `DistributedContext`.
+- the cross-cutting concern value to be injected, such as `SpanContext` or `DistributedContext`.
 - the carrier that holds propagation fields. For example, an outgoing message or http request.
 - the `Setter` invoked for each propagation key to add or remove.
 
@@ -99,7 +112,7 @@ Required arguments:
 - the carrier holds propagation fields. For example, an outgoing message or http request.
 - the instance of `Getter` invoked for each propagation key to get.
 
-Returns the non-null extracted value.
+Returns the non-null cross-cutting concern extracted value.
 
 #### Getter argument
 
@@ -118,4 +131,72 @@ Required arguments:
 - the carrier of propagation fields, such as an HTTP request.
 - the key of the field.
 
-The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text format implemenations MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`).
+The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text `Format` implementions MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`).
+
+## Composite Propagator
+
+Implementations MUST offer a facility to group multiple `Propagator`s
+from different cross-cutting concerns in order to leverage them as a
+single entity.
+
+The resulting composite `Propagator` will invoke the `Propagators`
+in the order they were specified.
+
+Each composite `Propagator` will be bound to a specific `Format`, such
+as `HttpTextFormat`, as different `Format`s will likely operate on different
+data types.
+There MUST be functions to accomplish the following operations.
+
+- Create a composite propagator
+- Extract from a composite propagator
+- Inject into a composite propagator
+
+### Create a Composite Propagator
+
+Required arguments:
+
+- A list of `Propagator`s.
+
+Returns a new composite `Propagator` with the specified `Propagator`s.
+
+### Extract
+
+Required arguments:
+
+- A `Context`.
+- The carrier that holds propagation fields.
+- The instance of `Getter` invoked for each propagation key to get.
+
+### Inject
+
+Required arguments:
+
+- A `Context`.
+- The carrier that holds propagation fields.
+- The `Setter` invoked for each propagation key to add or remove.
+
+## Global Propagators
+
+Implementations MAY provide global `Propagator`s for
+each supported `Format`.
+
+If offered, the global `Propagator`s should default to a composite `Propagator`
+containing W3C Trace Context and Correlation Context `Propagator`s,
+in order to provide propagation even in the presence of no-op
+OpenTelemetry implementations.
+
+### Get Global Propagator
+
+This method MUST exist for each supported `Format`.
+
+Returns a global `Propagator`. This usually will be composite instance.
+
+### Set Global Propagator
+
+This method MUST exist for each supported `Format`.
+
+Sets the global `Propagator` instance.
+
+Required parameters:
+
+- A `Propagator`. This usually will be a composite instance.

specification/overview.md

@@ -237,8 +237,9 @@ for an example.
 
 ## Propagators
 
-OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext`
-into text format. Currently there is one type of propagator:
+OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values
+such as `SpanContext` and `DistributedContext` into a `Format`. Currently there is one
+type of propagator:
 
 - `HTTPTextFormat` which is used to inject and extract a value as text into carriers that travel
  in-band across process boundaries.