From cfa058aa18c63300265cd0febc70c34d423bd1ca Mon Sep 17 00:00:00 2001 From: jkwatson Date: Tue, 6 Oct 2020 10:39:26 -0700 Subject: [PATCH 1/7] Update the baggage spec to include opaque metadata. Also update the description of the propagator to clarify metadata propagation. --- CHANGELOG.md | 2 ++ specification/baggage/api.md | 13 ++++++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e1d0f51e774..e921250e316 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,6 +43,8 @@ New: ([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994)) - Add Metric SDK specification (partial): covering terminology and Accumulator component ([#626](https://github.com/open-telemetry/opentelemetry-specification/pull/626)) +- Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation + ([TODO](https://gitnub.com/todo)) Updates: diff --git a/specification/baggage/api.md b/specification/baggage/api.md index fb99bc5539f..a576584acd3 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -64,13 +64,16 @@ contains a `Baggage` with the new value. REQUIRED parameters: -`Name` the name for which to set the value. +`Name` The name for which to set the value. This is string-valued. -`Value` the value to set. +`Value` The value to set. This is string-valued. OPTIONAL parameters: -`Context` the context containing the `Baggage` in which to set the baggage entry. +`Metadata` Optional metadata associated with the name-value pair. An opaque string with no +semantic meaning. + +`Context` The context containing the `Baggage` in which to set the baggage entry. ### Remove baggage @@ -104,6 +107,10 @@ The API layer MAY include the following `Propagator`s: * A `TextMapPropagator` implementing the [W3C Baggage Specification](https://w3c.github.io/baggage). +Note: The W3C baggage specification does not currently assign semantic meaning to the optional metadata. +On `extract`, the propagator should store all metadata per entry as a single opaque string. On `inject`, +the propagator should append the metadata per the W3C specification format. + ## 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 From b158c36ffca5a5fadd37384b0d876de6ac1f9302 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Tue, 6 Oct 2020 10:47:25 -0700 Subject: [PATCH 2/7] fix CHANGELOG update --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e921250e316..9379bd2cae9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ release. ## Unreleased +- Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation + ([#1066](https://github.com/open-telemetry/opentelemetry-specification/pull/1066)) + New: - Change Status to be consistent with Link and Event @@ -43,8 +46,6 @@ New: ([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994)) - Add Metric SDK specification (partial): covering terminology and Accumulator component ([#626](https://github.com/open-telemetry/opentelemetry-specification/pull/626)) -- Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation - ([TODO](https://gitnub.com/todo)) Updates: From a04d2f29dd2d58e26efdebd7047ccba8f6ad53b3 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Tue, 6 Oct 2020 11:06:48 -0700 Subject: [PATCH 3/7] Add clarification that the Metadata should be an opaque wrapper for the string, not hte string itself. --- specification/baggage/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index a576584acd3..179151af7c0 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -70,8 +70,8 @@ REQUIRED parameters: OPTIONAL parameters: -`Metadata` Optional metadata associated with the name-value pair. An opaque string with no -semantic meaning. +`Metadata` Optional metadata associated with the name-value pair. This should be an opaque wrapper +for a string with no semantic meaning. Left opaque to allow for future functionality. `Context` The context containing the `Baggage` in which to set the baggage entry. @@ -108,8 +108,8 @@ The API layer MAY include the following `Propagator`s: * A `TextMapPropagator` implementing the [W3C Baggage Specification](https://w3c.github.io/baggage). Note: The W3C baggage specification does not currently assign semantic meaning to the optional metadata. -On `extract`, the propagator should store all metadata per entry as a single opaque string. On `inject`, -the propagator should append the metadata per the W3C specification format. +On `extract`, the propagator should store all metadata as a single metadata instance per entry. +On `inject`, the propagator should append the metadata per the W3C specification format. ## Conflict Resolution From edfdb53b4d8263f426897fd21c511852fcbdeb61 Mon Sep 17 00:00:00 2001 From: John Watson Date: Wed, 7 Oct 2020 11:25:17 -0700 Subject: [PATCH 4/7] Update CHANGELOG.md Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9379bd2cae9..55e3e9facc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ release. ## Unreleased +New: + - Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation ([#1066](https://github.com/open-telemetry/opentelemetry-specification/pull/1066)) From e167f774e381280cfaef1c728c5f4f22ca7838ec Mon Sep 17 00:00:00 2001 From: jkwatson Date: Wed, 7 Oct 2020 12:52:36 -0700 Subject: [PATCH 5/7] Add some additional baggage propagator implementation notes. --- specification/baggage/api.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 179151af7c0..8cb6d972c11 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -108,9 +108,17 @@ The API layer MAY include the following `Propagator`s: * A `TextMapPropagator` implementing the [W3C Baggage Specification](https://w3c.github.io/baggage). Note: The W3C baggage specification does not currently assign semantic meaning to the optional metadata. + On `extract`, the propagator should store all metadata as a single metadata instance per entry. On `inject`, the propagator should append the metadata per the W3C specification format. +Notes: + +If the propagator is unable to parse the `baggage` header, `extract` MUST return a Context with no baggage entries in it. + +If the `baggage` header is present, but contains no entries, `extract` MUST return a Context with +no baggage entries in it. + ## 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 From 51caf31dca1a50ddecb6fb57d4fe7e62a0bfc8b8 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Wed, 7 Oct 2020 12:55:17 -0700 Subject: [PATCH 6/7] update name/value description, based on feedback --- specification/baggage/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index 8cb6d972c11..ed82e8564e5 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -64,9 +64,9 @@ contains a `Baggage` with the new value. REQUIRED parameters: -`Name` The name for which to set the value. This is string-valued. +`Name` The name for which to set the value, of type string. -`Value` The value to set. This is string-valued. +`Value` The value to set, of type string. OPTIONAL parameters: From 9899958aae34f49fbfc4952ec3f0e7a687e40454 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Wed, 7 Oct 2020 14:23:36 -0700 Subject: [PATCH 7/7] update CHANGELOG.md from rebase --- CHANGELOG.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 55e3e9facc9..fb1aaa38e7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,9 +11,6 @@ New: - Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation ([#1066](https://github.com/open-telemetry/opentelemetry-specification/pull/1066)) - -New: - - Change Status to be consistent with Link and Event ([#1067](https://github.com/open-telemetry/opentelemetry-specification/pull/1067)) - Clarify env variables in otlp exporter