From 526aae6ea1751d82a757c5fe6c6d8c27ec31797e Mon Sep 17 00:00:00 2001 From: James Moessis Date: Mon, 18 Nov 2024 13:14:31 +1100 Subject: [PATCH 01/16] Adds GetAll to Getter propagation as optional function --- specification/context/api-propagators.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 1dad75893e7..9ca275d6ad7 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -196,11 +196,11 @@ Returns a new `Context` derived from the `Context` passed as argument. #### Getter argument -Getter is an argument in `Extract` that get value from given field +Getter is an argument in `Extract` that gets value(s) from given field. `Getter` allows a `TextMapPropagator` to read propagated fields from a carrier. -One of the ways to implement it is `Getter` class with `Get` and `Keys` methods +One of the ways to implement it is `Getter` class with methods `Get`, `Keys`, and `GetAll` as described below. Languages may decide on alternative implementations and expose corresponding methods as delegates or other ways. @@ -229,6 +229,24 @@ Required arguments: 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. +##### GetAll + +The GetAll function MUST NOT require explicit implementation to satisfy the base `Getter` type. +Language implementations have the flexibility to incorporate this optional +functionality in various ways, such as by providing a default GetAll method, or +by creating a new type that extends the base `Getter` type. + +If explicitly implemented, the GetAll function MUST return all values of the given propagation key. +It SHOULD return them in the same order as they appear in the carrier. +If the key doesn't exist, it SHOULD return an empty collection. + +Required arguments: + +- the carrier of propagation fields, such as an HTTP request. +- the key of the field. + +The GetAll 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. + ## Injectors and Extractors as Separate Interfaces Languages can choose to implement a `Propagator` type as a single object From eb980cdcb638ece6f37bad191bb5c2a6a521aa4d Mon Sep 17 00:00:00 2001 From: James Moessis Date: Mon, 18 Nov 2024 13:36:57 +1100 Subject: [PATCH 02/16] add entry to changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9041036f9c5..afbd7c3f516 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. ### Context +- Propagation - Extract handles multiple values on carrier using same key. + [#4295](https://github.com/open-telemetry/opentelemetry-specification/pull/4295) + ### Traces ### Metrics From 3eaeffc14593a12e035e330369001cb8797c6bad Mon Sep 17 00:00:00 2001 From: James Moessis Date: Mon, 18 Nov 2024 14:57:06 +1100 Subject: [PATCH 03/16] appease linter --- CHANGELOG.md | 2 +- specification/context/api-propagators.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index afbd7c3f516..dfae9d728cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ release. ### Context -- Propagation - Extract handles multiple values on carrier using same key. +- Propagation - Extract handles multiple values on carrier using same key. [#4295](https://github.com/open-telemetry/opentelemetry-specification/pull/4295) ### Traces diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 9ca275d6ad7..2a3e07c6697 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -22,6 +22,7 @@ + [Getter argument](#getter-argument) - [Keys](#keys) - [Get](#get) + - [GetAll](#getall) - [Injectors and Extractors as Separate Interfaces](#injectors-and-extractors-as-separate-interfaces) - [Composite Propagator](#composite-propagator) * [Create a Composite Propagator](#create-a-composite-propagator) From 8c80655994cd59575f44188f8d1c0f9416fb92b6 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Tue, 19 Nov 2024 09:17:04 +1100 Subject: [PATCH 04/16] apply @trask suggestion to change changelog wording Co-authored-by: Trask Stalnaker --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dfae9d728cb..75d9a73f5b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ release. ### Context -- Propagation - Extract handles multiple values on carrier using same key. +- Propagation - Adds optional GetAll method to Getter, allowing for the retrieval of multiple keys for the same value. [#4295](https://github.com/open-telemetry/opentelemetry-specification/pull/4295) ### Traces From 5c111de4b8f539cdd22205b3114a0809b48d5042 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Tue, 19 Nov 2024 09:17:30 +1100 Subject: [PATCH 05/16] Apply @trask suggestion to change document section status Co-authored-by: Trask Stalnaker --- specification/context/api-propagators.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 2a3e07c6697..41103f6f261 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -232,6 +232,8 @@ The Get function is responsible for handling case sensitivity. If the getter is ##### GetAll +**Status**: [Development](../document-status.md) + The GetAll function MUST NOT require explicit implementation to satisfy the base `Getter` type. Language implementations have the flexibility to incorporate this optional functionality in various ways, such as by providing a default GetAll method, or From 5a68e75e5198d483b162071fa4ef3b171ad52281 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Tue, 19 Nov 2024 09:22:25 +1100 Subject: [PATCH 06/16] change document status to 'stable, except where otherwise specified' --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 41103f6f261..aa51b9b7634 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -1,6 +1,6 @@ # Propagators API -**Status**: [Stable, Feature-Freeze](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified.
Table of Contents From 459b589bdf9ce88f06a71277b22b6490a7cd8097 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Tue, 19 Nov 2024 10:31:57 +1100 Subject: [PATCH 07/16] commit @jack-berg suggestion regarding 'an http' vs 'a http' Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index aa51b9b7634..375775fdce8 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -248,7 +248,7 @@ Required arguments: - the carrier of propagation fields, such as an HTTP request. - the key of the field. -The GetAll 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. +The GetAll function is responsible for handling case sensitivity. If the getter is intended to work with an HTTP request object, the getter MUST be case insensitive. ## Injectors and Extractors as Separate Interfaces From 1eb620e27d0382ee286e8a6a4e201aeee20a2623 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Tue, 19 Nov 2024 10:56:37 +1100 Subject: [PATCH 08/16] Reword backward compatibility paragraph as per @jack-berg review comments --- specification/context/api-propagators.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 375775fdce8..81ec874584c 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -234,10 +234,11 @@ The Get function is responsible for handling case sensitivity. If the getter is **Status**: [Development](../document-status.md) -The GetAll function MUST NOT require explicit implementation to satisfy the base `Getter` type. -Language implementations have the flexibility to incorporate this optional -functionality in various ways, such as by providing a default GetAll method, or -by creating a new type that extends the base `Getter` type. +For many language implementations, the GetAll function will be added after the stable release of Getter. +For these languages, requiring implementations of Getter to include GetAll constitutes a breaking change +since instrumentation which previously functioned would fail. Language implementations should be cognizant +of this, and add GetAll in a way that retains backwards compatibility. For example, by providing a default +GetAll implementation based on Get, or by creating an extended Getter type. If explicitly implemented, the GetAll function MUST return all values of the given propagation key. It SHOULD return them in the same order as they appear in the carrier. From f30ef2ba95bd5117f40130723ef663d882c72ce6 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Tue, 19 Nov 2024 11:19:45 +1100 Subject: [PATCH 09/16] Consistent use of "an HTTP" Co-authored-by: Trask Stalnaker --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 81ec874584c..d36cb1f518a 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -228,7 +228,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. +The Get function is responsible for handling case sensitivity. If the getter is intended to work with an HTTP request object, the getter MUST be case insensitive. ##### GetAll From 4f0021b0829e1285a42e52e1e1fa3dd2cf804a9d Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 10:36:28 +1100 Subject: [PATCH 10/16] apply @pellared suggestion correcting the order of key/value MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75d9a73f5b8..2a556d387e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ release. ### Context -- Propagation - Adds optional GetAll method to Getter, allowing for the retrieval of multiple keys for the same value. +- Adds optional `GetAll` method to `Getter` in Propagation API, allowing for the retrieval of multiple values for the same key. [#4295](https://github.com/open-telemetry/opentelemetry-specification/pull/4295) ### Traces From fadf8d112dea6fc70654f4b2d08b6cc1cff74722 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 10:40:05 +1100 Subject: [PATCH 11/16] apply backtick as suggested by @pellared MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index d36cb1f518a..4f0a5880a9d 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -240,7 +240,7 @@ since instrumentation which previously functioned would fail. Language implement of this, and add GetAll in a way that retains backwards compatibility. For example, by providing a default GetAll implementation based on Get, or by creating an extended Getter type. -If explicitly implemented, the GetAll function MUST return all values of the given propagation key. +If explicitly implemented, the `GetAll` function MUST return all values of the given propagation key. It SHOULD return them in the same order as they appear in the carrier. If the key doesn't exist, it SHOULD return an empty collection. From 35db9a1e9f654c92e5220dfb9881ecd4085fa9ff Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 11:51:02 +1100 Subject: [PATCH 12/16] commit backtick suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 4f0a5880a9d..67b8de058a0 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -238,7 +238,7 @@ For many language implementations, the GetAll function will be added after the s For these languages, requiring implementations of Getter to include GetAll constitutes a breaking change since instrumentation which previously functioned would fail. Language implementations should be cognizant of this, and add GetAll in a way that retains backwards compatibility. For example, by providing a default -GetAll implementation based on Get, or by creating an extended Getter type. +`GetAll` implementation based on Get, or by creating an extended `Getter` type. If explicitly implemented, the `GetAll` function MUST return all values of the given propagation key. It SHOULD return them in the same order as they appear in the carrier. From acd7501a015c795920eba199e10dcffcc2304423 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 11:51:15 +1100 Subject: [PATCH 13/16] commit backtick suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 67b8de058a0..cd968e08360 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -234,7 +234,7 @@ The Get function is responsible for handling case sensitivity. If the getter is **Status**: [Development](../document-status.md) -For many language implementations, the GetAll function will be added after the stable release of Getter. +For many language implementations, the `GetAll` function will be added after the stable release of `Getter`. For these languages, requiring implementations of Getter to include GetAll constitutes a breaking change since instrumentation which previously functioned would fail. Language implementations should be cognizant of this, and add GetAll in a way that retains backwards compatibility. For example, by providing a default From 1305662c6714bf61cd1564d7a91f3456354f24cf Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 11:51:28 +1100 Subject: [PATCH 14/16] commit backtick suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index cd968e08360..ceef38f54e9 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -235,7 +235,7 @@ The Get function is responsible for handling case sensitivity. If the getter is **Status**: [Development](../document-status.md) For many language implementations, the `GetAll` function will be added after the stable release of `Getter`. -For these languages, requiring implementations of Getter to include GetAll constitutes a breaking change +For these languages, requiring implementations of `Getter` to include `GetAll` constitutes a breaking change since instrumentation which previously functioned would fail. Language implementations should be cognizant of this, and add GetAll in a way that retains backwards compatibility. For example, by providing a default `GetAll` implementation based on Get, or by creating an extended `Getter` type. From 37c0e5a0026898e608a7b9fd0ccc2e621dd1d0f4 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 11:51:42 +1100 Subject: [PATCH 15/16] commit backtick suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index ceef38f54e9..46606e52aed 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -237,7 +237,7 @@ The Get function is responsible for handling case sensitivity. If the getter is For many language implementations, the `GetAll` function will be added after the stable release of `Getter`. For these languages, requiring implementations of `Getter` to include `GetAll` constitutes a breaking change since instrumentation which previously functioned would fail. Language implementations should be cognizant -of this, and add GetAll in a way that retains backwards compatibility. For example, by providing a default +of this, and add `GetAll` in a way that retains backwards compatibility. For example, by providing a default `GetAll` implementation based on Get, or by creating an extended `Getter` type. If explicitly implemented, the `GetAll` function MUST return all values of the given propagation key. From e093c60821e0385ae4d88b4ef1490fafaf08e5f0 Mon Sep 17 00:00:00 2001 From: James Moessis Date: Wed, 27 Nov 2024 11:51:54 +1100 Subject: [PATCH 16/16] commit backtick suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 46606e52aed..99b8e6756ab 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -249,7 +249,7 @@ Required arguments: - the carrier of propagation fields, such as an HTTP request. - the key of the field. -The GetAll function is responsible for handling case sensitivity. If the getter is intended to work with an HTTP request object, the getter MUST be case insensitive. +The `GetAll` function is responsible for handling case sensitivity. If the getter is intended to work with an HTTP request object, the getter MUST be case insensitive. ## Injectors and Extractors as Separate Interfaces