Add the Context notion.

specification/api-propagators.md

@@ -5,9 +5,7 @@
 Table of Contents
 </summary>
 
-- [Binary Format](#binary-format)
-  - [ToBytes](#tobytes)
-  - [FromBytes](#frombytes)
+- [Overview] (#overview)
 - [HTTP Text Format](#http-text-format)
   - [Fields](#fields)
   - [Inject](#inject)
@@ -19,43 +17,15 @@ Table of Contents
 
 </details>
 
-Propagators API consists of two main formats:
+## Overview
 
-- `BinaryFormat` is used to serialize and deserialize a value into a binary representation.
-- `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`.
-
-## Binary Format
-
-`BinaryFormat` is a formatter to serialize and deserialize a value into a binary format.
-
-`BinaryFormat` MUST expose the APIs that serializes values into bytes,
-and deserializes values from bytes.
-
-### ToBytes
-
-Serializes the given value into the on-the-wire representation.
-
-Required arguments:
-
-- the value to serialize, can be `SpanContext` or `DistributedContext`.
+Propagators leverage the `Context` to inject and extract
+data for each cross-cutting concern, such as traces and metrics.
 
-Returns the on-the-wire byte representation of the value.
+The Propagators API consists of the following formats:
 
-### FromBytes
-
-Creates a value from the given on-the-wire encoded representation.
-
-If the value could not be parsed, the underlying implementation SHOULD decide to return ether
-an empty value, an invalid value, or a valid value.
-
-Required arguments:
-
-- on-the-wire byte representation of the value.
-
-Returns a value deserialized from bytes.
+- `HTTPTextFormat` is used to inject values into and extract values from carriers as text that travel
+  in-band across process boundaries.
 
 ## HTTP Text Format
 
@@ -94,7 +64,7 @@ Injects the value downstream. For example, as http headers.
 
 Required arguments:
 
-- the value to be injected, can be `SpanContext` or `DistributedContext`.
+- A `Context`. The Propagator MUST retrieve the appropiate value from the `Context` first, which can be `SpanContext`, `DistributedContext` or another cross-cutting concern context. For languages supporting current `Context` state this argument is OPTIONAL, defaulting to the current `Context` instance.
 - 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.
 
@@ -120,18 +90,24 @@ The implemenation SHOULD preserve casing (e.g. it should not transform `Content-
 
 ### Extract
 
-Extracts the value from upstream. For example, as http headers.
+Extracts the value from an incoming request. For example, from the headers of an HTTP request.
 
-If the value could not be parsed, the underlying implementation will decide to return an
-object representing either an empty value, an invalid value, or a valid value. Implementations
-MUST not return null.
+If a cross-cutting concern value could not be parsed, the implementation MUST set a value
+it deems appropiate, and it MUST NOT throw any exception.
 
 Required arguments:
 
+- A `Context`. For languages supporting current `Context` state this argument is OPTIONAL, defaulting to the current `Context` instance.
 - 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 a new `Context` as child of the `Context` passed as argument,
+containing the extracted value, which can be a `SpanContext`,
+`DistributedContext` or another cross-cutting concern context.
+
+The `Context` passed as an argument MUST NOT be modified.
+
+If the extracted value is a `SpanContext`, its `IsRemote` property MUST be set to true.
 
 #### Getter argument
 

specification/api-tracing.md

@@ -15,8 +15,6 @@ Table of Contents
     * [GetCurrentSpan](#getcurrentspan)
     * [WithSpan](#withspan)
     * [SpanBuilder](#spanbuilder)
-    * [GetBinaryFormat](#getbinaryformat)
-    * [GetHttpTextFormat](#gethttptextformat)
 * [SpanContext](#spancontext)
 * [Span](#span)
   * [Span creation](#span-creation)
@@ -127,14 +125,15 @@ mechanism, for instance the `ServiceLoader` class in Java.
 
 The `Tracer` MUST provide methods to:
 
-- Get the currently active `Span`
 - Create a new `Span`
+
+The `Tracer` SHOULD provide methods to:
+
+- Get the currently active `Span`
 - Make a given `Span` as active
 
-The `Tracer` SHOULD allow end users to configure other tracing components that
-control how `Span`s are passed across process boundaries, including the binary
-and text format `Propagator`s used to serialize `Span`s created by the
-`Tracer`.
+The `Tracer` MUST internally leverage the context layer in order to handle the
+current `Span` state and how `Span`s are passed across process boundaries.
 
 When getting the current span, the `Tracer` MUST return a placeholder `Span`
 with an invalid `SpanContext` if there is no currently active `Span`.
@@ -145,18 +144,13 @@ SHOULD create each new `Span` as a child of its active `Span` unless an
 explicit parent is provided or the option to create a span without a parent is
 selected, or the current active `Span` is invalid.
 
-The `Tracer` MUST provide a way to update its active `Span`, and MAY provide
+The `Tracer` SHOULD provide a way to update its active `Span` and MAY provide
 convenience methods to manage a `Span`'s lifetime and the scope in which a
 `Span` is active. When an active `Span` is made inactive, the previously-active
 `Span` SHOULD be made active. A `Span` maybe finished (i.e. have a non-null end
 time) but stil active. A `Span` may be active on one thread after it has been
 made inactive on another.
 
-The implementation MUST provide no-op binary and text `Propagator`s, which the
-`Tracer` SHOULD use by default if other propagators are not configured. SDKs
-SHOULD use the W3C HTTP Trace Context as the default text format. For more
-details, see [trace-context](https://github.com/w3c/trace-context).
-
 ## SpanContext
 
 A `SpanContext` represents the portion of a `Span` which must be serialized and

specification/context.md

@@ -0,0 +1,96 @@
+# Context
+
+<details>
+<summary>
+Table of Contents
+</summary>
+
+- [Overview](#overview)
+- [Get value](#get-value)
+- [Set value](#set-value)
+- [Remove value](#remove-value)
+- [Optional operations](#optional-operations)
+    - [Get current Context](#get-current-context)
+    - [Set current Context](#set-current-context)
+
+</details>
+
+## Overview
+
+`Context` is a propagation mechanism which carries execution-scoped values
+across API boundaries and between logically associated execution units.
+Cross-cutting concerns access their data in-process using the same shared
+`Context` object.
+
+Languages are expected to use the single, widely used `Context` implementation
+if one exists for them. In the cases where an extremely clear, pre-existing
+option is not available, OpenTelemetry MUST provide its own `Context`
+implementation. Depending on the language, its usage may be either explicit
+or implicit.
+
+`Context` can be considered as an implementation detail of the SDK.
+Users will manipulate `Context` through the cross-cutting concerns APIs
+rather than directly.
+
+Users writing instrumentation in languages that
+use `Context` implicitly are discouraged to use the `Context` API directly.
+
+`Context` is expected to have the following operations, with their
+respective language differences:
+
+## 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 concern identifier.
+
+The API MUST return the value in the `Context` for the specified concern
+identifier.
+
+## 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 concern identifier.
+- The value to be set.
+
+The API MUST return a new `Context` containing the new value.
+The `Context` passed as parameter MUST NOT be modified.
+
+## Remove value
+
+Concerns can clear their local state in a specified `Context`.
+
+The API MUST accept the following parameters:
+
+- The `Context`.
+- The concern identifier.
+
+The API MUST return a new `Context` with the value cleared.
+The `Context` passed as parameter MUST NOT be modified.
+
+## Optional Global operations
+
+These operations are optional, and 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.
+
+### Set current Context
+
+Associates a `Context` with the caller's current execution unit.
+
+The API MUST accept the following parameters:
+
+- The `Context`.

specification/overview.md

@@ -235,12 +235,22 @@ OpenTelemetry
 [proto](https://github.com/open-telemetry/opentelemetry-proto/blob/a46c815aa5e85a52deb6cb35b8bc182fb3ca86a0/src/opentelemetry/proto/agent/common/v1/common.proto#L28-L96)
 for an example.
 
+## Context Propagation
+
+All of OpenTelemetry cross-cutting concerns, such as traces and metrics,
+share an underlying `Context` mechanism for storing state and
+accessing data across the lifespan of a distributed transaction.
+
+See the [Context](context.md)
+
 ## Propagators
 
 OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext`
-into a binary or text format. Currently there are two types of propagators:
+into any of the supported formats. Observe that `Propagators` leverage the underlying
+`Context` to both access and record cross-cutting concerns data.
+
+Currently there is one type of propagators:
 
-- `BinaryFormat` which is used to serialize and deserialize a value into a binary representation.
 - `HTTPTextFormat` which is used to inject and extract a value as text into carriers that travel
   in-band across process boundaries.