Recommend custom header "otcorrelations" over w3c correlation-context (#517)

* Change w3c correlation context to custom header

* use set-cookie format

* rename header to otbaggage

* update to header name in poll

* fix indentation level

* fix links

Author: dyladan

specification/context/api-propagators.md

@@ -195,7 +195,8 @@ 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,
+containing the W3C Trace Context Propagator and the Correlation Context `Propagator`
+specified in [api-correlationcontext.md](../correlationcontext/api.md#serialization),
 in order to provide propagation even in the presence of no-op
 OpenTelemetry implementations.
 

specification/correlationcontext/api.md

@@ -13,6 +13,7 @@ Table of Contents
   - [Remove correlation](#remove-correlation)
   - [Clear correlations](#clear-correlations)
 - [CorrelationContext Propagation](#correlationcontext-propagation)
+  - [Serialization](#serialization)
 - [Conflict Resolution](#conflict-resolution)
 
 </details>
@@ -29,8 +30,6 @@ The Correlations API consists of:
 `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.
-`CorrelationContext` MUST be serialized according to the editor's draft of the [W3C Correlation Context](https://w3c.github.io/correlation-context/)
-specification.
 
 ### Get correlations
 
@@ -102,6 +101,37 @@ OPTIONAL parameters:
 `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/correlation-context/) 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": "[email protected]",
+  "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

specification/overview.md

@@ -196,7 +196,6 @@ name/value pairs, called `CorrelationContext`. `CorrelationContext` is intended
 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.
 
-The `CorrelationContext` implements the editor's draft of the [W3C Correlation-Context specification](https://w3c.github.io/correlation-context/).
 While `CorrelationContext` can be used to prototype other cross-cutting concerns, this mechanism is primarily intended
 to convey values for the OpenTelemetry observability systems.