diff --git a/specification/distributedcontext-api.md b/specification/distributedcontext-api.md index d76ec26a2a5..4a15ecaedc7 100644 --- a/specification/distributedcontext-api.md +++ b/specification/distributedcontext-api.md @@ -2,6 +2,14 @@ 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 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 contest 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. @@ -129,3 +137,74 @@ Enter Scope 1 Current Entries E1=V1/M1, E2=V2/M2 <== E2 is restored. Close Scope 1 ``` + +# DistributedContext + +## GetIterator + +Returns an iterator over the entries in this `DistributedContext`. +The order of entries is not significant. The iterator MUST not modify the underlying 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`. + \ No newline at end of file diff --git a/terminology.md b/terminology.md index 2b95fb20609..57eb62c1d53 100644 --- a/terminology.md +++ b/terminology.md @@ -108,6 +108,15 @@ TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemet ## DistributedContext +**DistributedContext** is an abstract data type that represents 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 contest properties to logs and traces. + +**DistributedContext** is a recommended name but languages can have more language-specific names like **dctx**. + ### Entry An **Entry** is used to label anything that is associated with a specific operation,