From f9112aa83f9a890f56603bbcb298dcfade04ba80 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 5 Feb 2020 02:11:10 -0600 Subject: [PATCH 01/14] Initial Propagators update for OTEP 66. --- specification/api-propagators.md | 82 ++++++++++++++++++++++++++++++-- 1 file changed, 77 insertions(+), 5 deletions(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 5dd6433eda6..0df2b82882d 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -5,6 +5,7 @@ Table of Contents +- [Overview](#overview) - [Binary Format](#binary-format) - [ToBytes](#tobytes) - [FromBytes](#frombytes) @@ -16,10 +17,22 @@ Table of Contents - [Extract](#extract) - [Getter argument](#getter) - [Get](#get) +- [Composite Propagator](#composite-propagator) +- [Global Propagators](#global-propagators) -Propagators API consists of two main formats: +## 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 into RPC requests. 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. + +The Propagators API defines two main formats: - `BinaryFormat` is used to serialize and deserialize a value into a binary representation. - `HTTPTextFormat` is used to inject and extract a value as text into carriers that travel @@ -59,8 +72,8 @@ Returns a value deserialized from bytes. ## 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. @@ -94,7 +107,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. @@ -131,7 +144,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 @@ -151,3 +164,62 @@ Required arguments: - 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`). + +## 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 formats will likely work on a different +data types. + +### Create Composite Propagator + +Required arguments: + +- A list of `Propagator`s. + +Returns a new composite `Propagator` with the specified `Propagator`s. + +### Extract + +- A `Context`. +- The carrier that holds propagation fields. +- the `Setter` invoked for each propagation key to add or remove. + +### Inject + +- A `Context`. +- The carrier that holds propagation fields. +- The instance of `Getter` invoked for each propagation key to get. + +## Global Propagators + +Implementations can optionally provide global `Propagator`s for +each supported format. + +If offered, the global `Propagator`s should default to a composite `Propagator` +containing W3C TraceContext and CorrelationContext `Propagator`s, +in order to provide propagation even in the presence of no-op +OpenTelemetry implementations. + +### Get Propagator + +This method MUST exist for each supported format. + +Returns a global `Propagator`. This usually will be composite instance. + +### Set 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. From 4dc7c6cd524f11dc277df7d308df0fab308949f5 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 5 Feb 2020 02:22:44 -0600 Subject: [PATCH 02/14] Fix style. --- specification/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 0df2b82882d..e864c1d5251 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -178,7 +178,7 @@ Each composite `Propagator` will be bound to a specific format, such as `HttpTextFormat`, as different formats will likely work on a different data types. -### Create Composite Propagator +### Create a Composite Propagator Required arguments: From 07d1f444b01b3c630cab77b756f0f042d67080e5 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 5 Feb 2020 18:51:29 -0600 Subject: [PATCH 03/14] Initial feedback pass. --- specification/api-propagators.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index e864c1d5251..4ef1255c651 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -26,8 +26,8 @@ Table of Contents 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 into RPC requests. Each concern creates a set of `Propagator`s -for every supported format. +context data to and from RPC requests. 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. @@ -208,13 +208,13 @@ containing W3C TraceContext and CorrelationContext `Propagator`s, in order to provide propagation even in the presence of no-op OpenTelemetry implementations. -### Get Propagator +### Get Global Propagator This method MUST exist for each supported format. Returns a global `Propagator`. This usually will be composite instance. -### Set Propagator +### Set Global Propagator This method MUST exist for each supported format. From c75e1e1d1c40117130812f3537207403aa98f580 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 5 Feb 2020 18:53:27 -0600 Subject: [PATCH 04/14] Update specification/api-propagators.md Co-Authored-By: Tyler Yahn --- specification/api-propagators.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 4ef1255c651..745e793bedf 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -177,6 +177,11 @@ in the order they were specified. Each composite `Propagator` will be bound to a specific format, such as `HttpTextFormat`, as different formats will likely work on a 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 From 7297fe776e2dda3067121dc5495c4a476e6daf4f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 5 Feb 2020 18:53:52 -0600 Subject: [PATCH 05/14] Update specification/api-propagators.md Co-Authored-By: Tyler Yahn --- specification/api-propagators.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 745e793bedf..fde9649ed7b 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -193,6 +193,8 @@ Returns a new composite `Propagator` with the specified `Propagator`s. ### Extract +Required arguments: + - A `Context`. - The carrier that holds propagation fields. - the `Setter` invoked for each propagation key to add or remove. From ecec4950dfc7e494d87e8061eb52d9c3e1a1ae65 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 5 Feb 2020 18:55:11 -0600 Subject: [PATCH 06/14] Update specification/api-propagators.md Co-Authored-By: Tyler Yahn --- specification/api-propagators.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index fde9649ed7b..7b558474a4c 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -201,6 +201,8 @@ Required arguments: ### Inject +Required arguments: + - A `Context`. - The carrier that holds propagation fields. - The instance of `Getter` invoked for each propagation key to get. From 616d307187608439cff969b94fa26887aec3fd6c Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 6 Feb 2020 19:01:24 -0600 Subject: [PATCH 07/14] Update specification/api-propagators.md Co-Authored-By: Tyler Yahn --- specification/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index 7b558474a4c..58e6e9e1e76 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -175,7 +175,7 @@ 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 formats will likely work on a different +as `HttpTextFormat`, as different formats will likely operate on different data types. There MUST be functions to accomplish the following operations. From 3460697ebcaffce24ecbae67bd1155d65c8b5f1e Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 7 Feb 2020 09:22:04 -0600 Subject: [PATCH 08/14] Update specification/api-propagators.md Co-Authored-By: Armin Ruech --- specification/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index faed77875ec..bc0e03d52c1 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -165,7 +165,7 @@ Required arguments: - A `Context`. - The carrier that holds propagation fields. -- the `Setter` invoked for each propagation key to add or remove. +- The `Setter` invoked for each propagation key to add or remove. ### Inject From c433d240046cdc4c270a8a8721d8e61f67b594da Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 7 Feb 2020 16:24:46 +0100 Subject: [PATCH 09/14] Fix the mixed up getter/setter. --- specification/api-propagators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index bc0e03d52c1..ca3826aeba4 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -165,7 +165,7 @@ Required arguments: - A `Context`. - The carrier that holds propagation fields. -- The `Setter` invoked for each propagation key to add or remove. +- The instance of `Getter` invoked for each propagation key to get. ### Inject @@ -173,7 +173,7 @@ Required arguments: - A `Context`. - The carrier that holds propagation fields. -- The instance of `Getter` invoked for each propagation key to get. +- The `Setter` invoked for each propagation key to add or remove. ## Global Propagators From caca9a6f6d96ea1025a86c35daa4479de6729290 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 7 Feb 2020 09:27:24 -0600 Subject: [PATCH 10/14] Update specification/api-propagators.md Co-Authored-By: Armin Ruech --- specification/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index ca3826aeba4..a80b46b6289 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -177,7 +177,7 @@ Required arguments: ## Global Propagators -Implementations can optionally provide global `Propagator`s for +Implementations MAY provide global `Propagator`s for each supported format. If offered, the global `Propagator`s should default to a composite `Propagator` From b06e03cc06da5d6966af2eb2128b112067f203b7 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 7 Feb 2020 09:27:42 -0600 Subject: [PATCH 11/14] Update specification/api-propagators.md Co-Authored-By: Armin Ruech --- specification/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index a80b46b6289..f4939a88b52 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -181,7 +181,7 @@ Implementations MAY provide global `Propagator`s for each supported format. If offered, the global `Propagator`s should default to a composite `Propagator` -containing W3C TraceContext and CorrelationContext `Propagator`s, +containing W3C Trace Context and Correlation Context `Propagator`s, in order to provide propagation even in the presence of no-op OpenTelemetry implementations. From ba0b300da8a2457cfa0b06c23c286153824cced8 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 10 Feb 2020 18:47:08 +0100 Subject: [PATCH 12/14] Do not use RPC in api-propagators --- specification/api-propagators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index f4939a88b52..d8d2aa78c8c 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -23,8 +23,8 @@ Table of Contents 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 RPC requests. Each concern creates a set -of `Propagator`s for every supported format. +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. From c37c59752a714925950eef82adac96fcdaa1796e Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 10 Feb 2020 18:55:10 +0100 Subject: [PATCH 13/14] Use Format instead of format. --- specification/api-propagators.md | 18 +++++++++--------- specification/overview.md | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index d8d2aa78c8c..10871bb683c 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -24,19 +24,19 @@ Table of Contents 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. +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: +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 @@ -131,7 +131,7 @@ 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 @@ -142,8 +142,8 @@ 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 formats will likely operate on different +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. @@ -178,7 +178,7 @@ Required arguments: ## Global Propagators Implementations MAY provide global `Propagator`s for -each supported format. +each supported `Format`. If offered, the global `Propagator`s should default to a composite `Propagator` containing W3C Trace Context and Correlation Context `Propagator`s, @@ -187,13 +187,13 @@ OpenTelemetry implementations. ### Get Global Propagator -This method MUST exist for each supported format. +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. +This method MUST exist for each supported `Format`. Sets the global `Propagator` instance. diff --git a/specification/overview.md b/specification/overview.md index a027ee1c40b..9fde2f32199 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -238,7 +238,7 @@ for an example. ## Propagators OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext` -into text format. Currently there is one type of propagator: +into text `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. From 57a76fc137f2f4f39106c2e993b3166d89b12f5d Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 10 Feb 2020 19:02:26 +0100 Subject: [PATCH 14/14] Clarification on format in overview.md --- specification/overview.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/overview.md b/specification/overview.md index 9fde2f32199..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.