Adding Correlations API and removing DistributedContext

README.md

@@ -13,7 +13,7 @@ The OpenTelemetry specification describes the cross-language requirements and ex
  - [Package/Library Layout](specification/library-layout.md)
  - [Concurrency and Thread-Safety](specification/concurrency.md)
 - API Specification
- - [DistributedContext](specification/api-distributedcontext.md)
+ - [CorrelationContext](specification/api-correlationcontext.md)
  - [Propagators](specification/api-propagators.md)
  - [Tracing](specification/api-tracing.md)
  - [Metrics](specification/api-metrics.md)

specification/api-correlationcontext.md

@@ -0,0 +1,79 @@
+# Correlations API
+
+`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 [W3C Correlation Context](https://w3c.github.io/correlation-context/) specification.
+
+## 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).
+
+## CorrelationContext
+
+### GetCorrelations
+
+Returns the name/value pairs in this `CorrelationContext`. 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 this `CorrelationContext`.
+
+### GetCorrelation
+
+To access the value for a name/value pair by a prior event, the Correlations 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 from which to get the correlation.
+
+### SetCorrelation
+
+To record the value for a name/value pair, the Correlations API SHALL provide a function which
+takes a context, a name, and a value as input. Returns an updated `Context` which
+contains the new value.
+
+REQUIRED parameters:
+
+`Name` the name for which to set the value.
+
+`Value` the value to set.
+
+OPTIONAL parameters:
+
+`Context` the context to which the value will be set.
+
+### RemoveCorrelation
+
+To delete a name/value pair, the Correlations API SHALL provide a function which takes a context
+and a name as input. Returns an updated `Context` which no longer contains the selected name.
+
+REQUIRED parameters:
+
+`Name` the name to remove.
+
+OPTIONAL parameters:
+
+`Context` the context from which to remove the correlation.
+
+### ClearCorrelations
+
+To avoid sending any name/value pairs to an untrusted process, the Correlations API SHALL provide
+a function to remove all Correlations from a context. Returns an updated `Context`
+with no correlations.
+
+OPTIONAL parameters:
+
+`Context` the context from which to remove all correlations.
+
+### CorrelationContext Propagation
+
+`CorrelationContext` MAY be propagated across process boundaries or across any arbitrary boundaries
+(process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons.

specification/api-propagators.md

@@ -40,7 +40,7 @@ Serializes the given value into the on-the-wire representation.
 
 Required arguments:
 
-- the value to serialize, can be `SpanContext` or `DistributedContext`.
+- the value to serialize, can be `SpanContext` or `CorrelationContext`.
 
 Returns the on-the-wire byte representation of the value.
 
@@ -94,7 +94,7 @@ Injects the value downstream. For example, as http headers.
 
 Required arguments:
 
-- the value to be injected, can be `SpanContext` or `DistributedContext`.
+- the value to be injected, can be `SpanContext` or `CorrelationContext`.
 - 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.
 

specification/library-layout.md

@@ -17,7 +17,7 @@ api
  ├── metrics
  ├── trace
  │ └── propagation
- ├── distributedcontext
+ ├── correlationcontext
  │ └── propagation
  ├── internal
  └── logs
@@ -33,16 +33,11 @@ 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.
 
-### [/distributedcontext](api-distributedcontext.md)
+### [/correlationcontext](api-correlationcontext.md)
 
-This directory describes the DistributedContext API that can be used to manage context propagation
+This directory describes the CorrelationContext API that can be used to manage context propagation
 and metrics-related labeling.
 
-This API consists of a few main classes:
-
-- `Entry` is used to label anything that is associated with a specific operation, such as an HTTP request.
-- An `Entry` consists of `EntryMetadata`, `EntryKey`, and `EntryValue`.
-
 ### [/trace](api-tracing.md)
 
 This API consist of a few main classes:
@@ -71,7 +66,7 @@ sdk
  ├── metrics
  ├── resource
  ├── trace
- ├── distributedcontext
+ ├── correlationcontext
  ├── internal
  └── logs
 ```
@@ -93,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/distributedcontext`
+### `/sdk/correlationcontext`
 
 ### [/sdk/trace](sdk-tracing.md)