diff --git a/CHANGELOG.md b/CHANGELOG.md index e1d0f51e774..fb1aaa38e7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ release. New: +- Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation + ([#1066](https://github.com/open-telemetry/opentelemetry-specification/pull/1066)) - 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 diff --git a/specification/baggage/api.md b/specification/baggage/api.md index fb99bc5539f..ed82e8564e5 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, of type string. -`Value` the value to set. +`Value` The value to set, of type string. OPTIONAL parameters: -`Context` the context containing the `Baggage` in which to set the baggage entry. +`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. ### Remove baggage @@ -104,6 +107,18 @@ 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