diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 484b6bdf77d..10871bb683c 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -5,6 +5,7 @@ Table of Contents +- [Overview](#overview) - [HTTP Text Format](#http-text-format) - [Fields](#fields) - [Inject](#inject) @@ -13,22 +14,34 @@ Table of Contents - [Extract](#extract) - [Getter argument](#getter) - [Get](#get) +- [Composite Propagator](#composite-propagator) +- [Global Propagators](#global-propagators) -Propagators API currently consists of one format: +## Overview + +Cross-cutting concerns send their state to the next process using +`Propagator`s, which are defined as objects used to read and write +context data to and from messages exchanged by the applications. +Each concern creates a set of `Propagator`s for every supported `Format`. + +The Propagators API is expected to be leveraged by users writing +instrumentation libraries. + +Propagators API currently consists of one `Format`: - `HTTPTextFormat` is used to inject and extract a value as text into carriers that travel in-band across process boundaries. Deserializing must set `IsRemote` to true on the returned `SpanContext`. -A binary format will be added in the future. +A binary `Format` will be added in the future. ## HTTP Text Format -`HTTPTextFormat` is a formatter that injects and extracts a value as text into carriers that -travel in-band across process boundaries. +`HTTPTextFormat` is a formatter that injects and extracts a cross-cutting concern +value as text into carriers that travel in-band across process boundaries. Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as RPC/HTTP request headers. @@ -62,7 +75,7 @@ Injects the value downstream. For example, as http headers. Required arguments: -- the value to be injected, can be `SpanContext` or `DistributedContext`. +- the cross-cutting concern value to be injected, such as `SpanContext` or `DistributedContext`. - 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. @@ -99,7 +112,7 @@ Required arguments: - the carrier holds propagation fields. For example, an outgoing message or http request. - the instance of `Getter` invoked for each propagation key to get. -Returns the non-null extracted value. +Returns the non-null cross-cutting concern extracted value. #### Getter argument @@ -118,4 +131,72 @@ Required arguments: - the carrier of propagation fields, such as an HTTP request. - the key of the field. -The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text format implemenations MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`). +The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text `Format` implementions MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`). + +## Composite Propagator + +Implementations MUST offer a facility to group multiple `Propagator`s +from different cross-cutting concerns in order to leverage them as a +single entity. + +The resulting composite `Propagator` will invoke the `Propagators` +in the order they were specified. + +Each composite `Propagator` will be bound to a specific `Format`, such +as `HttpTextFormat`, as different `Format`s will likely operate on different +data types. +There MUST be functions to accomplish the following operations. + +- Create a composite propagator +- Extract from a composite propagator +- Inject into a composite propagator + +### Create a Composite Propagator + +Required arguments: + +- A list of `Propagator`s. + +Returns a new composite `Propagator` with the specified `Propagator`s. + +### Extract + +Required arguments: + +- A `Context`. +- The carrier that holds propagation fields. +- The instance of `Getter` invoked for each propagation key to get. + +### Inject + +Required arguments: + +- A `Context`. +- The carrier that holds propagation fields. +- The `Setter` invoked for each propagation key to add or remove. + +## Global Propagators + +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, +in order to provide propagation even in the presence of no-op +OpenTelemetry implementations. + +### Get Global Propagator + +This method MUST exist for each supported `Format`. + +Returns a global `Propagator`. This usually will be composite instance. + +### Set Global Propagator + +This method MUST exist for each supported `Format`. + +Sets the global `Propagator` instance. + +Required parameters: + +- A `Propagator`. This usually will be a composite instance. diff --git a/specification/overview.md b/specification/overview.md index a027ee1c40b..ae6ccd83fba 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -237,8 +237,9 @@ for an example. ## Propagators -OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext` -into text format. Currently there is one type of propagator: +OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values +such as `SpanContext` and `DistributedContext` into a `Format`. Currently there is one +type of propagator: - `HTTPTextFormat` which is used to inject and extract a value as text into carriers that travel in-band across process boundaries.