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,100 @@
+# CorrelationContext API
+
+<details>
+<summary>
+Table of Contents
+</summary>
+
+- [Overview](#overview)
+    - [Get correlations](#get-correlations)
+    - [Get correlation](#get-correlation)
+    - [Set correlation](#set-correlation)
+    - [Remove correlation](#remove-correlation)
+    - [Clear correlations](#clear-correlations)
+- [CorrelationContext Propagation](#correlationcontext-propagation)
+- [Conflict Resolution](#conflict-resolution)
+
+</details>
+
+## Overview
+
+`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
+
+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`.
+
+OPTIONAL parameters:
+
+`Context` the context from which to get the correlations.
+
+### Get correlation
+
+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.
+
+### Set correlation
+
+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.
+
+### Remove correlation
+
+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.
+
+### Clear correlations
+
+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.
+
+## 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).

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)