From b5995562c1a09cb613f4e36dfbce447652e405ad Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 21 Jan 2020 13:26:17 -0800 Subject: [PATCH 01/18] Renaming DistributedContext to CorrelationContext Updating DistributedContext to CorrelationContext as per [otep-66](https://github.com/open-telemetry/oteps/blob/master/text/0066-separate-context-propagation.md#Correlations-API). Updated the following: - added correlations API details - removing Entry as a separate class in favour of name/value pair to align more closely with the w3c spec - library layout, file name and README - overview Signed-off-by: Alex Boten --- README.md | 2 +- specification/api-correlationcontext.md | 100 +++++++++++ specification/api-distributedcontext.md | 226 ------------------------ specification/api-propagators.md | 4 +- specification/library-layout.md | 15 +- specification/overview.md | 42 +++-- 6 files changed, 131 insertions(+), 258 deletions(-) create mode 100644 specification/api-correlationcontext.md delete mode 100644 specification/api-distributedcontext.md diff --git a/README.md b/README.md index d7487f64423..102802d2369 100644 --- a/README.md +++ b/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) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md new file mode 100644 index 00000000000..a40d1d82fb9 --- /dev/null +++ b/specification/api-correlationcontext.md @@ -0,0 +1,100 @@ +# Correlations API + +`CorrelationContext` is an abstract data type represented by set of name/value pairs describing user +defined properties. Each name in `CorrelationContext` is associated with exactly one value. +`CorrelationContext` is serialized using the [W3C Correlation Context](https://w3c.github.io/correlation-context/) specification and is +used to annotate telemetry. Those values can be used to add dimension to the metric or +additional context properties to logs and traces. + +`CorrelationContext` is a recommended name but languages can have more +language-specific names like `cctx`. + +### Conflict Resolution + +If a new name/value pair is added and its name conflicts with an existing pair, then the new pair takes precedence. The value +is replaced by the most recent value (regardless of it is locally generated or received from a remote peer). Replacement is limited to a +scope in which the conflict arises. When the scope is closed the original value prior to the conflict is restored. For example, + +``` +T# - entry names +V# - entry values + +Enter Scope 1 + Current Entries E1=V1, E2=V2 + Enter Scope 2 + Add entries E3=V3, E2=V4 + Current Entries E1=V1, E2=V4, E3=V3/M3 <== Value of E2 is replaced by V4. + Close Scope 2 + Current Entries E1=V1, E2=V2 <== E2 is restored. +Close Scope 1 +``` + +## CorrelationContext + +### GetCorrelations + +Returns the entries in this `CorrelationContext`. The order of entries is not +significant. Based on the language specification, the returned value can be +either an immutable collection or an immutable iterator to the collection of +entries in this `CorrelationContext`. + +### GetCorrelation + +To access the value for an entry by a prior event, the Correlations API +provides a function which 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 parameter: + +`Context` the context from which to get the correlation. + +`Name` entry name to return the value for. + +### SetCorrelation + +To record the value for an entry, the Correlations API provides a function which +takes a context, a name, and a value as input. Returns an updated `Context` which +contains the new value. + +Required parameter: + +`Context` the context to which the value will be set. + +`Name` entry name for which to set the value. + +`Value` entry value to set. + +### RemoveCorrelation + +To delete an entry, the Correlations API provides a function which takes a context +and a name as input. Returns an updated `Context` which no longer contains the selected `Name`. + +Required parameter: + +`Context` the context from which to remove the correlation. + +`Name` entry name to remove. + +### ClearCorrelations + +To avoid sending any entries to an untrusted process, the Correlation API provides +a function to remove all Correlations from a context. Returns an updated `Context` +with no correlations. + +Required parameter: + +`Context` the context from which to remove all correlations. + +### Limits + +Combined size of all entries should not exceed 8192 bytes before encoding. +The size restriction applies to the deserialized entries so that the set of decoded + `CorrelationContext`s is independent of the encoding format. + +### CorrelationContext Propagation + +`CorrelationContext` may be propagated across process boundaries or across any arbitrary boundaries +(process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons. +For example, one may propagate 'project-id' entry across all micro-services to break down metrics +by 'project-id'. diff --git a/specification/api-distributedcontext.md b/specification/api-distributedcontext.md deleted file mode 100644 index 8c38c0af037..00000000000 --- a/specification/api-distributedcontext.md +++ /dev/null @@ -1,226 +0,0 @@ -# DistributedContext API - -An `Entry` is used to label anything that is associated -with a specific operation, such as an HTTP request. - -`DistributedContext` is an abstract data type that represents a collection of entries. -Each key of `DistributedContext` is associated with exactly one value. `DistributedContext` is serializable, -to facilitate propagating it not only inside the process but also across process boundaries. -`DistributedContext` is used to annotate telemetry with the name:value pair `Entry`. -Those values can be used to add dimension to the metric or additional context properties to logs and traces. - -`DistributedContext` is a recommended name but languages can have more language-specific names like `dctx`. - -## Entry - -An `Entry` consists of EntryMetadata, EntryKey, and EntryValue. - -### EntryKey - -`EntryKey` is the name of the Entry. `EntryKey` along with `EntryValue` can be used to -aggregate and group stats, annotate traces and logs, etc. - -#### Restrictions - -- Must contain only printable ASCII (codes between 32 and 126 inclusive) -- Must have length greater than zero and less than 256. -- Must not be empty. - -#### Create - -Creates a new `EntryKey` with the given name in string. This is a static method. - -Required parameter: - -Name of the `EntryKey`. - -#### GetName - -Returns the name of the `EntryKey`. - -### EntryValue - -`EntryValue` is a string. It MUST contain only printable ASCII (codes between -32 and 126) - -#### Create - -Creates a new `EntryValue` with the given value in string. This is a static method. - -Required parameter: - -String value of the `EntryValue`. - -#### AsString - -Returns the string value of the `EntryValue`. - -### EntryMetadata - -`EntryMetadata` contains properties associated with an `Entry`. For now only the property `EntryTTL` -is defined. In future, additional properties may be added to address specific situations. - -The creator of entries determines metadata of an entry it creates. - -#### Create - -Creates a new `EntryMetadata` with the `EntryTTL`. This is a static method. - -Required parameter: - -`EntryTTL` that represents number of hops an entry can propagate. - -#### GetEntryTTL - -Returns the `EntryTTL`. - -#### EntryTTL - -`EntryTTL` is an integer that represents number of hops an entry can propagate. Anytime a sender serializes an entry, -sends it over the wire and receiver deserializes the entry then the entry is considered to have travelled one hop. -There could be one or more proxy(ies) between sender and receiver. Proxies are treated as transparent -entities and they may not create additional hops. Every propagation implementation should support an option -`decrementTTL` (default set to true) that allows proxies to set it to false. - -**For now, ONLY special values (0 and -1) are supported.** - -##### Special Values - -- **NO_PROPAGATION (0)**: An `Entry` with `EntryTTL` value of zero is considered to have local scope and - is used within the process it created. - -- **UNLIMITED_PROPAGATION (-1)**: An `Entry` with `EntryTTL` value of -1 can propagate unlimited hops. - `EntryTTL` value of -1 is typical used to represent a request, processing of which may span multiple entities. - -##### Example for EntryTTL > 0 - -On a server side typically there is no information about the caller besides ip/port, -but in every process there is a notion of "service_name" entry that is added as a "caller" entry before -serialization when a RPC/HTTP call is made. For the "caller" entry, desirable `EntryTTL` value is 1. - -Note that `EntryTTL` value of 1 is not supported at this time. The example is listed here simply to -show a possible use case for `EntryTTL` > 0. - -#### Processing at Receiver and Sender - -For now, limited processing is required on Sender and Receiver. However, for the sake of -completeness, future processing requirement is also listed here. These requirements are marked with -"**(future)**". - -This processing is done as part of entry propagator. - -##### At Receiver - -Upon receiving an entry from a remote entity, an entry extractor: - -- MUST decrement the value of `EntryTTL` by one if it is greater than zero. **(future)** -- MUST treat the value of `EntryTTL` as -1 if it is not present. -- MUST discard the `Entry` for any other value of `EntryTTL`. **(future)** - -##### At Sender - -Upon preparing to send an entry to a remote entity, an entry injector: - -- MUST send the entry AND include `EntryTTL` if its value is greater than 0. **(future)** -- MUST send the entry without `EntryTTL` if its value is -1. Absence of `EntryTTL` on the wire is treated as having `EntryTTL` of -1. - This is to optimize on-the-wire representation of common case. -- MUST not send the entry if the value of `EntryTTL` is 0. - -### Entry Conflict Resolution - -If a new entry conflicts with an existing entry then the new entry takes precedence. Entire `Entry` along -with `EntryValue` and `EntryMetadata` is replaced by the most recent entry (regardless of it is locally -generated or received from a remote peer). Replacement is limited to a scope in which the -conflict arises. When the scope is closed the original value and metadata prior to the conflict is restored. -For example, - -``` -T# - Entry keys -V# - Entry Values -M# - Entry Metadata - -Enter Scope 1 - Current Entries E1=V1/M1, E2=V2/M2 - Enter Scope 2 - Add Entries E3=V3/M3, E2=V4/M4 - Current Entries E1=V1/M1, E2=V4/M4, E3=V3/M3 <== Value/Metadata of E2 is replaced by V4/M4. - Close Scope 2 - Current Entries E1=V1/M1, E2=V2/M2 <== E2 is restored. -Close Scope 1 -``` - -## DistributedContext - -### GetEntries - -Returns the entries in this `DistributedContext`. -The order of entries is not significant. Based on the language specification, -the returned value can be either an immutable collection or an immutable iterator -to the collection of entries in this `DistributedContext`. - -### GetEntryValue - -Returns the `EntryValue` associated with the given `EntryKey`, or null if the given `EntryKey` -is not present. - -Required parameter: - -`EntryKey` entry key to return the value for. - -### Limits - -Combined size of all entries should not exceed 8192 bytes before encoding. -The size restriction applies to the deserialized entries so that the set of decoded - `DistributedContext`s is independent of the encoding format. - -### DistributedContext Propagation - -`DistributedContext` may be propagated across process boundaries or across any arbitrary boundaries -(process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons. -For example, one may propagate 'project-id' Entry across all micro-services to break down metrics -by 'project-id'. Not all entries in a `DistributedContext` should be propagated and not all entries in a `DistributedContext` -should be accepted from a remote peer. Hence, `DistributedContext` propagator must allow specifying an optional -list of ordered `EntryPropagationFilter`s for receiving entries or for forwarding entries or for both. -An `EntryPropagationFilter` list for receiving MAY be different than that for forwarding. - -If no filter is specified for receiving then all entries are received. -If no filter is specified for forwarding then all entries are forwarded except those that have `EntryTTL` of 0. - -#### EntryPropagationFilter - -Entry Propagation Filter consists of an action (`EntryPropagationFilterAction`) and a condition -(`EntryPropagationFilterMatchOperator` and `EntryPropagationFilterMatchString`). An `EntryKey` -is evaluated against condition of each `EntryPropagationFilter` in order. If the condition is evaluated -to true then action is taken according to `EntryPropagationFilterAction` and filter processing is stopped. -If the condition is evaluated to false then the `EntryKey` is processed against next `EntryPropagationFilter` -in the ordered list. If none of the condition is evaluated to true then the default -action is **Exclude**. - -##### EntryPropagationFilterAction - -This is an interface. Implementation of this interface takes appropriate action on the `Entry` if the -condition (`EntryPropagationFitlerMatchOperator` and `EntryPropagationFilterMatchString`) is evaluated to true. -At a minimum, `Exclude` and `Include` actions MUST be implemented. - -**Exclude** -If the `EntryPropagationFilterAction` is Exclude then any `Entry` whose `EntryKey` evaluates to true -with the condition (`EntryPropagationFitlerMatchOperator` and `EntryPropagationFilterMatchString`) -MUST be excluded. - -**Include** -If the `EntryPropagationFilterAction` is Include then any `Entry` whose `EntryKey` evaluates to true -with the condition (`EntryPropagationFitlerMatchOperator` and `EntryPropagationFilterMatchString`) -MUST be included. - -##### EntryPropagationFilterMatchOperator - -| Operator | Description | -|----------|-------------| -| EQUAL | The condition is evaluated to true if `EntryKey` is exactly same as `EntryPropagationFilterMatchString` | -| NOTEQUAL | The condition is evaluated to true if `EntryKey` is NOT exactly same as `EntryPropagationFilterMatchString` | -| HAS_PREFIX | The condition is evaluated to true if `EntryKey` begins with `EntryPropagationFilterMatchString` | - -##### EntryPropagationFilterMatchString - -It is a string to compare against EntryKey using `EntryPropagationFilterMatchOperator` in order to -include or exclude an `Entry`. diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 5dd6433eda6..f9745e04cda 100644 --- a/specification/api-propagators.md +++ b/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. diff --git a/specification/library-layout.md b/specification/library-layout.md index 1f609996bdd..a3221ef7960 100644 --- a/specification/library-layout.md +++ b/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) diff --git a/specification/overview.md b/specification/overview.md index e80e9e5ecd2..350a914d189 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -193,31 +193,35 @@ OpenTelemetry defines the naming convention for metric names as well as a well-known metric names in [Semantic Conventions](data-semantic-conventions.md) document. -## DistributedContext +## CorrelationContext -The **DistributedContext** exists to store labels that describe the context of an operation an application performs. It is intended to enable context that are custom to the application or integrations in contrast to other contexts, such as `SpanContext`. Only one **DistributedContext** should be associated with any particular operation. +In addition to trace propagation, OpenTelemetry provides a simple mechanism for propagating +name/value pairs, called **CorrelationContext**. The **CorrelationContext** is intended for +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. -For example, a web service can benefit from including context around what service has sent the request. Or a SaaS provider can include context about the API user or token that is responsible for that request. These values can be consumed from **DistributedContext** and used as an additional dimension for a metric, or additional context for logs and traces. +The **CorrelationContext** is based on the [W3C Correlation-Context specification](https://w3c.github.io/correlation-context/), +and implements the protocol as it is defined in that working group. While **CorrelationContext** +can be used to prototype other cross-cutting concerns, this mechanism is primarily intended +to convey values for the OpenTelemetry observability systems. -**DistributedContext** is a collection of key-value `Entry` pairs, with each key of associated with exactly one value. **DistributedContext** is serializable, -to facilitate propagating it not only inside the process but also across process boundaries. +These values can be consumed from **CorrelationContext** and used as an additional dimension for a metric, +or additional context for logs and traces. Some examples: -**DistributedContext** is a recommended name but languages can have more language-specific names like **dctx**. +- a web service can benefit from including context around what service has sent the request. +- a SaaS provider can include context about the API user or token that is responsible for that request +- determining that a particular browser version is associated with a failure in an image processing service -### Entry +**CorrelationContext** is a collection of name/value pairs, with each key of associated with +exactly one value and is serialized using the [W3C Correlation Context](https://w3c.github.io/correlation-context/) +specification. -An **Entry** is used to represent the labels that are contained inside the `DistributedContext`, representing values such as the service that originated the request, or vendor-specific data. It consists of an **EntryKey**, an **EntryValue** and an **EntryMetadata**. +For backwards compatibility with OpenTracing, Baggage is propagated as **CorrelationContext** when +using the OpenTracing bridge. New concerns with different criteria should consider creating new a new +cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but +use a new HTTP header to convey data throughout a distributed trace. -- **EntryKey** is the name of the **Entry**. **EntryKey** along with **EntryValue** - can be used to aggregate and group stats, annotate traces and logs, etc. **EntryKey** is - a string that contains only printable ASCII (codes between 32 and 126 inclusive) and with - a length greater than zero and less than 256. -- **EntryValue** is a string that contains only printable ASCII (codes between 32 and 126). -- **EntryMetadata** contains properties associated with an **Entry**. - For now only the property **EntryTTL** is defined. -- **EntryTTL** is an integer that represents number of hops an entry can propagate. - Anytime a sender serializes an entry, sends it over the wire and a receiver deserializes - the entry then the entry is considered to have travelled one hop. +`CorrelationContext` is a recommended name but languages can have more language-specific names like `cctx`. ## Resources @@ -237,7 +241,7 @@ for an example. ## Propagators -OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext` +OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `CorrelationContext` into a binary or text format. Currently there are two types of propagators: - `BinaryFormat` which is used to serialize and deserialize a value into a binary representation. From 9fd689b1a3b56839c9dd48256ab9859f26caaf22 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Thu, 23 Jan 2020 15:14:06 -0800 Subject: [PATCH 02/18] formatting fix Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index a40d1d82fb9..8d82fab7f12 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -9,7 +9,7 @@ additional context properties to logs and traces. `CorrelationContext` is a recommended name but languages can have more language-specific names like `cctx`. -### Conflict Resolution +## Conflict Resolution If a new name/value pair is added and its name conflicts with an existing pair, then the new pair takes precedence. The value is replaced by the most recent value (regardless of it is locally generated or received from a remote peer). Replacement is limited to a From 67e97aa93ed5de62909e06ffdc9979156fcd23a4 Mon Sep 17 00:00:00 2001 From: alrex Date: Fri, 24 Jan 2020 08:04:42 -0800 Subject: [PATCH 03/18] Update specification/overview.md Co-Authored-By: Armin Ruech --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index 350a914d189..ec05623789c 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -217,7 +217,7 @@ exactly one value and is serialized using the [W3C Correlation Context](https:// specification. For backwards compatibility with OpenTracing, Baggage is propagated as **CorrelationContext** when -using the OpenTracing bridge. New concerns with different criteria should consider creating new a new +using the OpenTracing bridge. New concerns with different criteria should consider creating a new cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but use a new HTTP header to convey data throughout a distributed trace. From c045ad2ccaffc522efdd9cb0e94e55867df6abb2 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 28 Jan 2020 21:01:10 -0800 Subject: [PATCH 04/18] Review feedback changes - update context to be an optional parameter - removing name recommendation - updating casing on REQUIRED - updating conflict resolution example Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 33 ++++++++++++++----------- specification/overview.md | 2 -- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 8d82fab7f12..6b06ef0f1a9 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -6,9 +6,6 @@ defined properties. Each name in `CorrelationContext` is associated with exactly used to annotate telemetry. Those values can be used to add dimension to the metric or additional context properties to logs and traces. -`CorrelationContext` is a recommended name but languages can have more -language-specific names like `cctx`. - ## Conflict Resolution If a new name/value pair is added and its name conflicts with an existing pair, then the new pair takes precedence. The value @@ -16,14 +13,14 @@ is replaced by the most recent value (regardless of it is locally generated or r scope in which the conflict arises. When the scope is closed the original value prior to the conflict is restored. For example, ``` -T# - entry names +E# - entry names V# - entry values Enter Scope 1 Current Entries E1=V1, E2=V2 Enter Scope 2 Add entries E3=V3, E2=V4 - Current Entries E1=V1, E2=V4, E3=V3/M3 <== Value of E2 is replaced by V4. + Current Entries E1=V1, E2=V4, E3=V3 <== Value of E2 is replaced by V4. Close Scope 2 Current Entries E1=V1, E2=V2 <== E2 is restored. Close Scope 1 @@ -45,44 +42,50 @@ provides a function which 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 parameter: - -`Context` the context from which to get the correlation. +REQUIRED parameters: `Name` entry name to return the value for. +OPTIONAL parameters: + +`Context` the context from which to get the correlation. + ### SetCorrelation To record the value for an entry, the Correlations API provides a function which takes a context, a name, and a value as input. Returns an updated `Context` which contains the new value. -Required parameter: - -`Context` the context to which the value will be set. +REQUIRED parameters: `Name` entry name for which to set the value. `Value` entry value to set. +OPTIONAL parameters: + +`Context` the context to which the value will be set. + ### RemoveCorrelation To delete an entry, the Correlations API provides a function which takes a context and a name as input. Returns an updated `Context` which no longer contains the selected `Name`. -Required parameter: - -`Context` the context from which to remove the correlation. +REQUIRED parameters: `Name` entry name to remove. +OPTIONAL parameters: + +`Context` the context from which to remove the correlation. + ### ClearCorrelations To avoid sending any entries to an untrusted process, the Correlation API provides a function to remove all Correlations from a context. Returns an updated `Context` with no correlations. -Required parameter: +OPTIONAL parameters: `Context` the context from which to remove all correlations. diff --git a/specification/overview.md b/specification/overview.md index ec05623789c..d8be4b86163 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -221,8 +221,6 @@ using the OpenTracing bridge. New concerns with different criteria should consid cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but use a new HTTP header to convey data throughout a distributed trace. -`CorrelationContext` is a recommended name but languages can have more language-specific names like `cctx`. - ## Resources `Resource` captures information about the entity for which telemetry is From 0de4b016f36450aa6446ff7a4a3369e0730e1da4 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 28 Jan 2020 23:21:10 -0800 Subject: [PATCH 05/18] Feedback fixes Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 12 ++++++------ specification/overview.md | 14 +++++++------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 6b06ef0f1a9..70d5771e689 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -30,7 +30,7 @@ Close Scope 1 ### GetCorrelations -Returns the entries in this `CorrelationContext`. The order of entries is not +Returns the entries in this `CorrelationContext`. The order of entries 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 entries in this `CorrelationContext`. @@ -38,7 +38,7 @@ entries in this `CorrelationContext`. ### GetCorrelation To access the value for an entry by a prior event, the Correlations API -provides a function which takes a context and a name as input, and returns a +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. @@ -52,7 +52,7 @@ OPTIONAL parameters: ### SetCorrelation -To record the value for an entry, the Correlations API provides a function which +To record the value for an entry, 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. @@ -68,7 +68,7 @@ OPTIONAL parameters: ### RemoveCorrelation -To delete an entry, the Correlations API provides a function which takes a context +To delete an entry, 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: @@ -81,7 +81,7 @@ OPTIONAL parameters: ### ClearCorrelations -To avoid sending any entries to an untrusted process, the Correlation API provides +To avoid sending any entries 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. @@ -97,7 +97,7 @@ The size restriction applies to the deserialized entries so that the set of deco ### CorrelationContext Propagation -`CorrelationContext` may be propagated across process boundaries or across any arbitrary boundaries +`CorrelationContext` MAY be propagated across process boundaries or across any arbitrary boundaries (process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons. For example, one may propagate 'project-id' entry across all micro-services to break down metrics by 'project-id'. diff --git a/specification/overview.md b/specification/overview.md index d8be4b86163..b1558a4eb69 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -196,27 +196,27 @@ document. ## CorrelationContext In addition to trace propagation, OpenTelemetry provides a simple mechanism for propagating -name/value pairs, called **CorrelationContext**. The **CorrelationContext** is intended for +name/value pairs, called `CorrelationContext`. `CorrelationContext` is intended for 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** is based on the [W3C Correlation-Context specification](https://w3c.github.io/correlation-context/), -and implements the protocol as it is defined in that working group. While **CorrelationContext** +The `CorrelationContext` is based on the [W3C Correlation-Context specification](https://w3c.github.io/correlation-context/), +and implements the protocol as it is defined in that working group. While `CorrelationContext` can be used to prototype other cross-cutting concerns, this mechanism is primarily intended to convey values for the OpenTelemetry observability systems. -These values can be consumed from **CorrelationContext** and used as an additional dimension for a metric, +These values can be consumed from `CorrelationContext` and used as an additional dimension for a metric, or additional context for logs and traces. Some examples: -- a web service can benefit from including context around what service has sent the request. +- a web service can benefit from including context around what service has sent the request - a SaaS provider can include context about the API user or token that is responsible for that request - determining that a particular browser version is associated with a failure in an image processing service -**CorrelationContext** is a collection of name/value pairs, with each key of associated with +`CorrelationContext` is a collection of name/value pairs, with each key of associated with exactly one value and is serialized using the [W3C Correlation Context](https://w3c.github.io/correlation-context/) specification. -For backwards compatibility with OpenTracing, Baggage is propagated as **CorrelationContext** when +For backwards compatibility with OpenTracing, Baggage is propagated as `CorrelationContext` when using the OpenTracing bridge. New concerns with different criteria should consider creating a new cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but use a new HTTP header to convey data throughout a distributed trace. From 7c379d9e1e450faed68162de0308bf120bdd5804 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 29 Jan 2020 07:48:51 -0800 Subject: [PATCH 06/18] Feedback fixes Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 70d5771e689..28e98faf6f5 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -1,15 +1,14 @@ # Correlations API -`CorrelationContext` is an abstract data type represented by set of name/value pairs describing user -defined properties. Each name in `CorrelationContext` is associated with exactly one value. -`CorrelationContext` is serialized using the [W3C Correlation Context](https://w3c.github.io/correlation-context/) specification and is -used to annotate telemetry. Those values can be used to add dimension to the metric or -additional context properties to logs and traces. +`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 conflicts with an existing pair, then the new pair takes precedence. The value -is replaced by the most recent value (regardless of it is locally generated or received from a remote peer). Replacement is limited to a +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). Replacement is limited to a scope in which the conflict arises. When the scope is closed the original value prior to the conflict is restored. For example, ``` From 8ee1b17c1da0cc533426eae764a581560b1756aa Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 29 Jan 2020 09:29:45 -0800 Subject: [PATCH 07/18] Feedback fixes Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 44 ++++++++++++------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 28e98faf6f5..fbd1a8ab0aa 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -12,16 +12,16 @@ is replaced with the added value (regardless if it is locally generated or recei scope in which the conflict arises. When the scope is closed the original value prior to the conflict is restored. For example, ``` -E# - entry names -V# - entry values +N# - names +V# - values Enter Scope 1 - Current Entries E1=V1, E2=V2 + Current name/value pairs N1=V1, N2=V2 Enter Scope 2 - Add entries E3=V3, E2=V4 - Current Entries E1=V1, E2=V4, E3=V3 <== Value of E2 is replaced by V4. + Add name/value pairs N3=V3, N2=V4 + Current name/value pairs N1=V1, N2=V4, N3=V3 <== Value of N2 is replaced by V4. Close Scope 2 - Current Entries E1=V1, E2=V2 <== E2 is restored. + Current name/value pairs N1=V1, N2=V2 <== N2 is restored. Close Scope 1 ``` @@ -29,21 +29,21 @@ Close Scope 1 ### GetCorrelations -Returns the entries in this `CorrelationContext`. The order of entries MUST NOT be +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 -entries in this `CorrelationContext`. +name/value pairs in this `CorrelationContext`. ### GetCorrelation -To access the value for an entry by a prior event, the Correlations API +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. +value. Returns the value associated with the given name, or null +if the given name is not present. REQUIRED parameters: -`Name` entry name to return the value for. +`Name` the name to return the value for. OPTIONAL parameters: @@ -51,15 +51,15 @@ OPTIONAL parameters: ### SetCorrelation -To record the value for an entry, the Correlations API SHALL provide a function which +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` entry name for which to set the value. +`Name` the name for which to set the value. -`Value` entry value to set. +`Value` the value to set. OPTIONAL parameters: @@ -67,12 +67,12 @@ OPTIONAL parameters: ### RemoveCorrelation -To delete an entry, 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`. +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` entry name to remove. +`Name` the name to remove. OPTIONAL parameters: @@ -80,7 +80,7 @@ OPTIONAL parameters: ### ClearCorrelations -To avoid sending any entries to an untrusted process, the Correlations API SHALL provide +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. @@ -90,13 +90,11 @@ OPTIONAL parameters: ### Limits -Combined size of all entries should not exceed 8192 bytes before encoding. -The size restriction applies to the deserialized entries so that the set of decoded +Combined size of all name/value pairs should not exceed 8192 bytes before encoding. +The size restriction applies to the deserialized name/value pairs so that the set of decoded `CorrelationContext`s is independent of the encoding format. ### CorrelationContext Propagation `CorrelationContext` MAY be propagated across process boundaries or across any arbitrary boundaries (process, $OTHER_BOUNDARY1, $OTHER_BOUNDARY2, etc) for various reasons. -For example, one may propagate 'project-id' entry across all micro-services to break down metrics -by 'project-id'. From 7531e24dbbd27ac811f13e6adb2dd7fceb484aac Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 29 Jan 2020 10:24:55 -0800 Subject: [PATCH 08/18] Feedback fixes Signed-off-by: Alex Boten --- specification/overview.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/specification/overview.md b/specification/overview.md index b1558a4eb69..5accbaff933 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -200,9 +200,8 @@ 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` is based on the [W3C Correlation-Context specification](https://w3c.github.io/correlation-context/), -and implements the protocol as it is defined in that working group. While `CorrelationContext` -can be used to prototype other cross-cutting concerns, this mechanism is primarily intended +The `CorrelationContext` implements 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. These values can be consumed from `CorrelationContext` and used as an additional dimension for a metric, @@ -212,10 +211,6 @@ or additional context for logs and traces. Some examples: - a SaaS provider can include context about the API user or token that is responsible for that request - determining that a particular browser version is associated with a failure in an image processing service -`CorrelationContext` is a collection of name/value pairs, with each key of associated with -exactly one value and is serialized using the [W3C Correlation Context](https://w3c.github.io/correlation-context/) -specification. - For backwards compatibility with OpenTracing, Baggage is propagated as `CorrelationContext` when using the OpenTracing bridge. New concerns with different criteria should consider creating a new cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but From 2e1dbe88209f1b65a934be814e018322aaa0d940 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 29 Jan 2020 10:45:07 -0800 Subject: [PATCH 09/18] Adding details around size limit Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index fbd1a8ab0aa..ead85df01ad 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -90,9 +90,9 @@ OPTIONAL parameters: ### Limits -Combined size of all name/value pairs should not exceed 8192 bytes before encoding. -The size restriction applies to the deserialized name/value pairs so that the set of decoded - `CorrelationContext`s is independent of the encoding format. +Combined size of all name/value pairs should not exceed 8192 bytes before encoding. After the size is +reached, correlations are dropped. The size restriction applies to the deserialized name/value pairs so +that the set of decoded `CorrelationContext`s is independent of the encoding format. ### CorrelationContext Propagation From 5f23702c9c36f9cd3f1d5dd507d04b0f76e859ea Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 29 Jan 2020 11:58:33 -0800 Subject: [PATCH 10/18] More updates A few more updates: - removing limits, these can be spec'd in the SDK - the scoping example doesn't make sense to keep here Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 23 +---------------------- 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index ead85df01ad..204ec7cbe9f 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -8,22 +8,7 @@ defined properties. Each name in `CorrelationContext` MUST be associated with ex ## 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). Replacement is limited to a -scope in which the conflict arises. When the scope is closed the original value prior to the conflict is restored. For example, - -``` -N# - names -V# - values - -Enter Scope 1 - Current name/value pairs N1=V1, N2=V2 - Enter Scope 2 - Add name/value pairs N3=V3, N2=V4 - Current name/value pairs N1=V1, N2=V4, N3=V3 <== Value of N2 is replaced by V4. - Close Scope 2 - Current name/value pairs N1=V1, N2=V2 <== N2 is restored. -Close Scope 1 -``` +is replaced with the added value (regardless if it is locally generated or received from a remote peer). ## CorrelationContext @@ -88,12 +73,6 @@ OPTIONAL parameters: `Context` the context from which to remove all correlations. -### Limits - -Combined size of all name/value pairs should not exceed 8192 bytes before encoding. After the size is -reached, correlations are dropped. The size restriction applies to the deserialized name/value pairs so -that the set of decoded `CorrelationContext`s is independent of the encoding format. - ### CorrelationContext Propagation `CorrelationContext` MAY be propagated across process boundaries or across any arbitrary boundaries From c5b911a97723de0197d4a85b9b8206268859d116 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 29 Jan 2020 19:53:44 -0800 Subject: [PATCH 11/18] Minor formatting update Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 204ec7cbe9f..5e3afd5f6e0 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -1,8 +1,8 @@ # 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. +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 From 9a388cfe14ef70df82ee22a3519700937881bcae Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 12 Feb 2020 11:20:03 -0800 Subject: [PATCH 12/18] adding missing parameter Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 5e3afd5f6e0..b192d63cbff 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -19,6 +19,10 @@ 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 remove the correlation. + ### GetCorrelation To access the value for a name/value pair by a prior event, the Correlations API From 0ab9f977d1f822b9ae2ccbc00df00db8b1ec20e5 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Thu, 13 Feb 2020 10:34:50 -0800 Subject: [PATCH 13/18] renaming methods, to match context spec change Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index b192d63cbff..cd42e107cd6 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -5,14 +5,9 @@ It is an abstract data type represented by a set of name/value pairs describing 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 +### 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 @@ -21,9 +16,9 @@ name/value pairs in this `CorrelationContext`. OPTIONAL parameters: -`Context` the context from which to remove the correlation. +`Context` the context from which to get the correlations. -### GetCorrelation +### 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 @@ -38,7 +33,7 @@ OPTIONAL parameters: `Context` the context from which to get the correlation. -### SetCorrelation +### 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 @@ -54,7 +49,7 @@ OPTIONAL parameters: `Context` the context to which the value will be set. -### RemoveCorrelation +### 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. @@ -67,7 +62,7 @@ OPTIONAL parameters: `Context` the context from which to remove the correlation. -### ClearCorrelations +### 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` @@ -77,7 +72,12 @@ OPTIONAL parameters: `Context` the context from which to remove all correlations. -### CorrelationContext Propagation +## 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). From 96067f7fd68ef28ff18ca7d016bb93a255fa60fe Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Thu, 13 Feb 2020 10:39:33 -0800 Subject: [PATCH 14/18] adding table of content Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index cd42e107cd6..4f5c6f07649 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -1,12 +1,28 @@ -# Correlations API +# CorrelationContext API + +
+ +Table of Contents + + +- [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) + +
+ +## 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 [W3C Correlation Context](https://w3c.github.io/correlation-context/) specification. -## CorrelationContext - ### Get correlations Returns the name/value pairs in this `CorrelationContext`. The order of name/value pairs MUST NOT be From 6484d067b0693575163f932bca2693853f0cfb95 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Thu, 13 Feb 2020 11:12:48 -0800 Subject: [PATCH 15/18] adding note about editor's draft Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 3 ++- specification/overview.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 4f5c6f07649..5a45efa7e44 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -21,7 +21,8 @@ Table of Contents `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. +`CorrelationContext` MUST be serialized according to the editor's draft of the [W3C Correlation Context](https://w3c.github.io/correlation-context/) +specification. ### Get correlations diff --git a/specification/overview.md b/specification/overview.md index 7c0c1b5f115..7cf85de5b81 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -200,7 +200,7 @@ 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 [W3C Correlation-Context specification](https://w3c.github.io/correlation-context/). +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. From 85d27666a554f6e304aaf1ec5d16d8863992f555 Mon Sep 17 00:00:00 2001 From: alrex Date: Tue, 18 Feb 2020 10:37:19 -0800 Subject: [PATCH 16/18] Update specification/overview.md Co-Authored-By: Reiley Yang --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index 5fa9f9f4a93..df1b670d1b4 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -211,7 +211,7 @@ or additional context for logs and traces. Some examples: - a SaaS provider can include context about the API user or token that is responsible for that request - determining that a particular browser version is associated with a failure in an image processing service -For backwards compatibility with OpenTracing, Baggage is propagated as `CorrelationContext` when +For backward compatibility with OpenTracing, Baggage is propagated as `CorrelationContext` when using the OpenTracing bridge. New concerns with different criteria should consider creating a new cross-cutting concern to cover their use-case; they may benefit from the W3C encoding format but use a new HTTP header to convey data throughout a distributed trace. From b32617f45f19a592854ed462d00f3f27dfa6d0da Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 18 Feb 2020 14:55:35 -0800 Subject: [PATCH 17/18] edit from feedback Signed-off-by: Alex Boten --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index df1b670d1b4..7d44c016dc7 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -204,7 +204,7 @@ The `CorrelationContext` implements the editor's draft of the [W3C Correlation-C While `CorrelationContext` can be used to prototype other cross-cutting concerns, this mechanism is primarily intended to convey values for the OpenTelemetry observability systems. -These values can be consumed from `CorrelationContext` and used as an additional dimension for a metric, +These values can be consumed from `CorrelationContext` and used as additional dimensions for metrics, or additional context for logs and traces. Some examples: - a web service can benefit from including context around what service has sent the request From 975d4c57a35f2286b670853c79f9040053a6d632 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 18 Feb 2020 15:28:14 -0800 Subject: [PATCH 18/18] adding more details around CorrelationContext Signed-off-by: Alex Boten --- specification/api-correlationcontext.md | 32 +++++++++++++++---------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/specification/api-correlationcontext.md b/specification/api-correlationcontext.md index 5a45efa7e44..9ed54eea9cf 100644 --- a/specification/api-correlationcontext.md +++ b/specification/api-correlationcontext.md @@ -1,4 +1,4 @@ -# CorrelationContext API +# Correlations API
@@ -6,6 +6,7 @@ Table of Contents - [Overview](#overview) + - [CorrelationContext](#correlationcontext) - [Get correlations](#get-correlations) - [Get correlation](#get-correlation) - [Set correlation](#set-correlation) @@ -18,6 +19,13 @@ Table of Contents ## Overview +The Correlations API consists of: + +- the `CorrelationContext` +- functions to interact with the `CorrelationContext` in a `Context` + +### CorrelationContext + `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. @@ -26,14 +34,14 @@ specification. ### Get correlations -Returns the name/value pairs in this `CorrelationContext`. The order of name/value pairs MUST NOT be +Returns the name/value pairs in the `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`. +name/value pairs in the `CorrelationContext`. OPTIONAL parameters: -`Context` the context from which to get the correlations. +`Context` the context containing the `CorrelationContext` from which to get the correlations. ### Get correlation @@ -48,13 +56,13 @@ REQUIRED parameters: OPTIONAL parameters: -`Context` the context from which to get the correlation. +`Context` the context containing the `CorrelationContext` 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. +takes a context, a name, and a value as input. Returns a new `Context` which +contains a `CorrelationContext` with the new value. REQUIRED parameters: @@ -64,12 +72,12 @@ REQUIRED parameters: OPTIONAL parameters: -`Context` the context to which the value will be set. +`Context` the context containing the `CorrelationContext` in which to set the correlation. ### 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. +and a name as input. Returns a new `Context` which no longer contains the selected name. REQUIRED parameters: @@ -77,17 +85,17 @@ REQUIRED parameters: OPTIONAL parameters: -`Context` the context from which to remove the correlation. +`Context` the context containing the `CorrelationContext` 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` +a function to remove all Correlations from a context. Returns a new `Context` with no correlations. OPTIONAL parameters: -`Context` the context from which to remove all correlations. +`Context` the context containing the `CorrelationContext` from which to remove all correlations. ## CorrelationContext Propagation