From e3479a6aa12e194b554ebdfba622e374da4bcfb5 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 5 Aug 2021 16:57:45 +0200 Subject: [PATCH 01/20] Add a section for OTel specific values in TraceState. --- specification/trace/api.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/specification/trace/api.md b/specification/trace/api.md index d5658197c34..a4eef2904ca 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -257,6 +257,23 @@ Such changes then make sense only right before or [telemetry data exporting](sdk.md#span-exporter). In both cases, `Propagator`s and `SpanExporter`s may create a modified `TraceState` copy before serializing it to the wire. +#### OTel specific values + +When setting values that are part of the OTel ecosystem, they MUST all be contained in a single entry using +the `otel` key, and the value MUST be a semicolon separated list of key-value pairs such as: + +* `otel=p:8;r:64` +* `otel=foo:bar;k1=13` + +New set values MUST be appended to existing `otel` entry in `TraceState`, unless an explicit override +is expected to happen, in order to preserve existing values beloging to other concerns. +For example, if a given concern K wants to set `k1:13`: + +* `otel=p:8;r:64` will become `otel=p:8;r:64;k1=13`. +* `otel=p:8,r:64;tkey=7` will become `otel:p8;r:64;k1=13`. + +Observe that the keys and values used within the `otel` value MUST all comply with the `TraceState` rules. + ## Span A `Span` represents a single operation within a trace. Spans can be nested to From 00cb453a1f80c1dff66170129f32c6753a10da26 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 5 Aug 2021 17:37:46 +0200 Subject: [PATCH 02/20] Update specification/trace/api.md Co-authored-by: Yuri Shkuro --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index a4eef2904ca..2c4d6f52e30 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -263,7 +263,7 @@ When setting values that are part of the OTel ecosystem, they MUST all be contai the `otel` key, and the value MUST be a semicolon separated list of key-value pairs such as: * `otel=p:8;r:64` -* `otel=foo:bar;k1=13` +* `otel=foo:bar;k1:13` New set values MUST be appended to existing `otel` entry in `TraceState`, unless an explicit override is expected to happen, in order to preserve existing values beloging to other concerns. From 59c30d15c2a871550f7456c131772eb8370ca3f3 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 5 Aug 2021 17:37:52 +0200 Subject: [PATCH 03/20] Update specification/trace/api.md Co-authored-by: Yuri Shkuro --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 2c4d6f52e30..06babf16e52 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -269,7 +269,7 @@ New set values MUST be appended to existing `otel` entry in `TraceState`, unless is expected to happen, in order to preserve existing values beloging to other concerns. For example, if a given concern K wants to set `k1:13`: -* `otel=p:8;r:64` will become `otel=p:8;r:64;k1=13`. +* `otel=p:8;r:64` will become `otel=p:8;r:64;k1:13`. * `otel=p:8,r:64;tkey=7` will become `otel:p8;r:64;k1=13`. Observe that the keys and values used within the `otel` value MUST all comply with the `TraceState` rules. From a9edb5f83daaa34f430d0446fb4fe8f3806b1e68 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 5 Aug 2021 17:38:46 +0200 Subject: [PATCH 04/20] Fix sample. --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 06babf16e52..a3fbb24be7f 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -270,7 +270,7 @@ is expected to happen, in order to preserve existing values beloging to other co For example, if a given concern K wants to set `k1:13`: * `otel=p:8;r:64` will become `otel=p:8;r:64;k1:13`. -* `otel=p:8,r:64;tkey=7` will become `otel:p8;r:64;k1=13`. +* `otel=p:8,r:64;k1:7` will become `otel:p8;r:64;k1:13`. Observe that the keys and values used within the `otel` value MUST all comply with the `TraceState` rules. From ba7b543e2c9a7dfef5f03ba56a28bade43cba46f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 11 Aug 2021 16:51:51 +0200 Subject: [PATCH 05/20] Apply feedback. --- specification/trace/api.md | 17 ----------------- specification/trace/sdk.md | 19 +++++++++++++++++++ 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index a3fbb24be7f..d5658197c34 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -257,23 +257,6 @@ Such changes then make sense only right before or [telemetry data exporting](sdk.md#span-exporter). In both cases, `Propagator`s and `SpanExporter`s may create a modified `TraceState` copy before serializing it to the wire. -#### OTel specific values - -When setting values that are part of the OTel ecosystem, they MUST all be contained in a single entry using -the `otel` key, and the value MUST be a semicolon separated list of key-value pairs such as: - -* `otel=p:8;r:64` -* `otel=foo:bar;k1:13` - -New set values MUST be appended to existing `otel` entry in `TraceState`, unless an explicit override -is expected to happen, in order to preserve existing values beloging to other concerns. -For example, if a given concern K wants to set `k1:13`: - -* `otel=p:8;r:64` will become `otel=p:8;r:64;k1:13`. -* `otel=p:8,r:64;k1:7` will become `otel:p8;r:64;k1:13`. - -Observe that the keys and values used within the `otel` value MUST all comply with the `TraceState` rules. - ## Span A `Span` represents a single operation within a trace. Spans can be nested to diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index ed46bbf6df6..7394fca921b 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -13,6 +13,7 @@ * [Id Generator](#id-generators) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) +* [OTel TraceState values](#otel-tracestate-values) @@ -680,5 +681,23 @@ public interface SpanExporter { } ``` +## OTel TraceState values + +When setting [TraceState](api#tracestate) values that are part of the OTel ecosystem, +they MUST all be contained in a single entry using the `ot` key, with the value being +a semicolon separated list of key-value pairs such as: + +* `ot=p:8;r:64` +* `ot=foo:bar;k1:13` + +Set values MUST be either updated or added to the `ot` entry in `TraceState`, +in order to preserve existing values belonging to other OTel concerns. For example, +if a given concern K wants to set `k1:13`: + +* `ot=p:8;r:64` will become `ot=p:8;r:64;k1:13`. +* `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. + +Keys and values MUST only contain alphanumeric characters. + [trace-flags]: https://www.w3.org/TR/trace-context/#trace-flags [otep-83]: https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md From 885c99adf485aebb78d7723c1ff814066268f2e4 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 19 Aug 2021 02:19:15 +0200 Subject: [PATCH 06/20] Use same notation as TraceContext. --- specification/trace/sdk.md | 48 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 7394fca921b..37e96bae368 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -683,6 +683,11 @@ public interface SpanExporter { ## OTel TraceState values +In alignment to the [TraceContext](https://www.w3.org/TR/trace-context/) specification, this section uses the +Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context/#bib-rfc5234), +including the DIGIT rule in that document. It also includes the OWS rule from +[RFC7230 section 3.2.3](https://httpwg.org/specs/rfc7230.html#whitespace). + When setting [TraceState](api#tracestate) values that are part of the OTel ecosystem, they MUST all be contained in a single entry using the `ot` key, with the value being a semicolon separated list of key-value pairs such as: @@ -690,6 +695,47 @@ a semicolon separated list of key-value pairs such as: * `ot=p:8;r:64` * `ot=foo:bar;k1:13` +The list can be formally defined as: + +``` +list = list-member *( ";" list-member ) +list-member = key ":" value +list-member = "" ; empty character +``` + +The complete list length MUST NOT exceed 256 characters, as defined by the +[TraceState value section](https://www.w3.org/TR/trace-context/#value), +and the used keys MUST be unique. + +### Key + +The key is an identifier that describes the OTel concern, consisting +of either one or two characters. Simple examples are `p`, `ts`, or `s1`. + +The key can be formally defined as: + +``` +key = lcalpha 0*1(lcalpha / DIGIT ) +lcalpha = %x61-7A ; a-z +``` + +### Value + +The value is an opaque string. Although it has no maximum allowed length, +it is recommended to use short values, as the **entire** list of key-values +MUST NOT exceed 256 characters. + +The value can be formally defined as: + +``` +value = *(chr) +chr = ucalpha / lcalpha / DIGIT / "." / "_" / "-" +ucalpha = %x41-5A ; A-Z +lcalpha = %x61-7A ; a-z +``` + +### Setting values + Set values MUST be either updated or added to the `ot` entry in `TraceState`, in order to preserve existing values belonging to other OTel concerns. For example, if a given concern K wants to set `k1:13`: @@ -697,7 +743,5 @@ if a given concern K wants to set `k1:13`: * `ot=p:8;r:64` will become `ot=p:8;r:64;k1:13`. * `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. -Keys and values MUST only contain alphanumeric characters. - [trace-flags]: https://www.w3.org/TR/trace-context/#trace-flags [otep-83]: https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md From 223c5cf8becd86485f0362567ff0d6ae5369af1a Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 19 Aug 2021 02:21:00 +0200 Subject: [PATCH 07/20] Remove unused OWS mention. --- specification/trace/sdk.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 37e96bae368..df97b19e495 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -685,8 +685,7 @@ public interface SpanExporter { In alignment to the [TraceContext](https://www.w3.org/TR/trace-context/) specification, this section uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context/#bib-rfc5234), -including the DIGIT rule in that document. It also includes the OWS rule from -[RFC7230 section 3.2.3](https://httpwg.org/specs/rfc7230.html#whitespace). +including the DIGIT rule in that document. When setting [TraceState](api#tracestate) values that are part of the OTel ecosystem, they MUST all be contained in a single entry using the `ot` key, with the value being From e067da0f890c0a2f96796f9987d5e7f136d4f0a0 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 19 Aug 2021 02:29:00 +0200 Subject: [PATCH 08/20] Fix link. --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index df97b19e495..ce77993a923 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -687,7 +687,7 @@ In alignment to the [TraceContext](https://www.w3.org/TR/trace-context/) specifi Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context/#bib-rfc5234), including the DIGIT rule in that document. -When setting [TraceState](api#tracestate) values that are part of the OTel ecosystem, +When setting [TraceState](api.md#tracestate) values that are part of the OTel ecosystem, they MUST all be contained in a single entry using the `ot` key, with the value being a semicolon separated list of key-value pairs such as: From bc36949f7fdd11c2016d374b6397b223aa85aca3 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 26 Aug 2021 15:31:13 +0200 Subject: [PATCH 09/20] Update specification/trace/sdk.md Co-authored-by: Yuri Shkuro --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index ce77993a923..1ebcd5d505d 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -708,7 +708,7 @@ and the used keys MUST be unique. ### Key -The key is an identifier that describes the OTel concern, consisting +The key is an identifier that describes an OTel concern, consisting of either one or two characters. Simple examples are `p`, `ts`, or `s1`. The key can be formally defined as: From 7a839f7242e179062589e0abb6882957dd0f3489 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 26 Aug 2021 15:41:29 +0200 Subject: [PATCH 10/20] Clarify values. --- specification/trace/sdk.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 1ebcd5d505d..032ab810418 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -699,7 +699,6 @@ The list can be formally defined as: ``` list = list-member *( ";" list-member ) list-member = key ":" value -list-member = "" ; empty character ``` The complete list length MUST NOT exceed 256 characters, as defined by the @@ -708,16 +707,18 @@ and the used keys MUST be unique. ### Key -The key is an identifier that describes an OTel concern, consisting -of either one or two characters. Simple examples are `p`, `ts`, or `s1`. +The key is an identifier that describes an OTel concern. +Simple examples are `p`, `ts`, or `s1`. The key can be formally defined as: ``` -key = lcalpha 0*1(lcalpha / DIGIT ) +key = lcalpha *(lcalpha / DIGIT ) lcalpha = %x61-7A ; a-z ``` +Specific keys used by OTel concerns MUST be defined as part as the Specification too. + ### Value The value is an opaque string. Although it has no maximum allowed length, From 85e9a9c9036d178f4b945c4475ae9035ff137565 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 26 Aug 2021 15:54:48 +0200 Subject: [PATCH 11/20] Prevent larger than 256 char values. --- specification/trace/sdk.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 032ab810418..71f86448788 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -743,5 +743,15 @@ if a given concern K wants to set `k1:13`: * `ot=p:8;r:64` will become `ot=p:8;r:64;k1:13`. * `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. +If setting a value ends up making the entire `ot` entry exceed the 256 characters limit, +SDKs are adviced to discard the operation and signal the user about the error, e.g. + +```go +traceState, err := SetTraceStateValue(traceState, value) +if err != nil { + // Could not set the specified value, traceState was not updated. +} +``` + [trace-flags]: https://www.w3.org/TR/trace-context/#trace-flags [otep-83]: https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md From b8dc7bdb0f6ac75066011b3dfc8fe185812557e3 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 26 Aug 2021 15:57:07 +0200 Subject: [PATCH 12/20] Fix typo. --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 71f86448788..e1d645caeed 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -744,7 +744,7 @@ if a given concern K wants to set `k1:13`: * `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. If setting a value ends up making the entire `ot` entry exceed the 256 characters limit, -SDKs are adviced to discard the operation and signal the user about the error, e.g. +SDKs are advised to discard the operation and signal the user about the error, e.g. ```go traceState, err := SetTraceStateValue(traceState, value) From 3e7bf627d0387a43f8836730f21a371ec7545d20 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 26 Aug 2021 16:31:09 +0200 Subject: [PATCH 13/20] Update specification/trace/sdk.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index e1d645caeed..d1978b4f6e8 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -744,7 +744,7 @@ if a given concern K wants to set `k1:13`: * `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. If setting a value ends up making the entire `ot` entry exceed the 256 characters limit, -SDKs are advised to discard the operation and signal the user about the error, e.g. +SDKs are advised to abort the operation and signal the user about the error, e.g. ```go traceState, err := SetTraceStateValue(traceState, value) From 47fde3fba47f7710d29aeafda745e0cc8fc0eee2 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 2 Sep 2021 17:00:00 +0200 Subject: [PATCH 14/20] Move trace state handling to its own document. --- specification/trace/sdk.md | 73 --------------------- specification/trace/tracestate-handling.md | 74 ++++++++++++++++++++++ 2 files changed, 74 insertions(+), 73 deletions(-) create mode 100644 specification/trace/tracestate-handling.md diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index d1978b4f6e8..ed46bbf6df6 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -13,7 +13,6 @@ * [Id Generator](#id-generators) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) -* [OTel TraceState values](#otel-tracestate-values) @@ -681,77 +680,5 @@ public interface SpanExporter { } ``` -## OTel TraceState values - -In alignment to the [TraceContext](https://www.w3.org/TR/trace-context/) specification, this section uses the -Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context/#bib-rfc5234), -including the DIGIT rule in that document. - -When setting [TraceState](api.md#tracestate) values that are part of the OTel ecosystem, -they MUST all be contained in a single entry using the `ot` key, with the value being -a semicolon separated list of key-value pairs such as: - -* `ot=p:8;r:64` -* `ot=foo:bar;k1:13` - -The list can be formally defined as: - -``` -list = list-member *( ";" list-member ) -list-member = key ":" value -``` - -The complete list length MUST NOT exceed 256 characters, as defined by the -[TraceState value section](https://www.w3.org/TR/trace-context/#value), -and the used keys MUST be unique. - -### Key - -The key is an identifier that describes an OTel concern. -Simple examples are `p`, `ts`, or `s1`. - -The key can be formally defined as: - -``` -key = lcalpha *(lcalpha / DIGIT ) -lcalpha = %x61-7A ; a-z -``` - -Specific keys used by OTel concerns MUST be defined as part as the Specification too. - -### Value - -The value is an opaque string. Although it has no maximum allowed length, -it is recommended to use short values, as the **entire** list of key-values -MUST NOT exceed 256 characters. - -The value can be formally defined as: - -``` -value = *(chr) -chr = ucalpha / lcalpha / DIGIT / "." / "_" / "-" -ucalpha = %x41-5A ; A-Z -lcalpha = %x61-7A ; a-z -``` - -### Setting values - -Set values MUST be either updated or added to the `ot` entry in `TraceState`, -in order to preserve existing values belonging to other OTel concerns. For example, -if a given concern K wants to set `k1:13`: - -* `ot=p:8;r:64` will become `ot=p:8;r:64;k1:13`. -* `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. - -If setting a value ends up making the entire `ot` entry exceed the 256 characters limit, -SDKs are advised to abort the operation and signal the user about the error, e.g. - -```go -traceState, err := SetTraceStateValue(traceState, value) -if err != nil { - // Could not set the specified value, traceState was not updated. -} -``` - [trace-flags]: https://www.w3.org/TR/trace-context/#trace-flags [otep-83]: https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md new file mode 100644 index 00000000000..38ffdc4b2b1 --- /dev/null +++ b/specification/trace/tracestate-handling.md @@ -0,0 +1,74 @@ +# TraceState Handling + +**Status**: [Experimental](../document-status.md) + +In alignment to the [TraceContext](https://www.w3.org/TR/trace-context/) specification, this section uses the +Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context/#bib-rfc5234), +including the DIGIT rule in that document. + +When setting [TraceState](api.md#tracestate) values that are part of the OTel ecosystem, +they MUST all be contained in a single entry using the `ot` key, with the value being +a semicolon separated list of key-value pairs such as: + +* `ot=p:8;r:64` +* `ot=foo:bar;k1:13` + +The list can be formally defined as: + +``` +list = list-member *( ";" list-member ) +list-member = key ":" value +``` + +The complete list length MUST NOT exceed 256 characters, as defined by the +[TraceState value section](https://www.w3.org/TR/trace-context/#value), +and the used keys MUST be unique. + +## Key + +The key is an identifier that describes an OTel concern. +Simple examples are `p`, `ts`, or `s1`. + +The key can be formally defined as: + +``` +key = lcalpha *(lcalpha / DIGIT ) +lcalpha = %x61-7A ; a-z +``` + +Specific keys used by OTel concerns MUST be defined as part as the Specification too. + +## Value + +The value is an opaque string. Although it has no maximum allowed length, +it is recommended to use short values, as the **entire** list of key-values +MUST NOT exceed 256 characters. + +The value can be formally defined as: + +``` +value = *(chr) +chr = ucalpha / lcalpha / DIGIT / "." / "_" / "-" +ucalpha = %x41-5A ; A-Z +lcalpha = %x61-7A ; a-z +``` + +## Setting values + +Set values MUST be either updated or added to the `ot` entry in `TraceState`, +in order to preserve existing values belonging to other OTel concerns. For example, +if a given concern K wants to set `k1:13`: + +* `ot=p:8;r:64` will become `ot=p:8;r:64;k1:13`. +* `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. + +If setting a value ends up making the entire `ot` entry exceed the 256 characters limit, +SDKs are advised to abort the operation and signal the user about the error, e.g. + +```go +traceState, err := SetTraceStateValue(traceState, value) +if err != nil { + // Could not set the specified value, traceState was not updated. +} +``` + From 75f01b1039f2266f27272bcfdb7da4d1d072f8a2 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 2 Sep 2021 17:09:28 +0200 Subject: [PATCH 15/20] Update specification/trace/tracestate-handling.md Co-authored-by: John Watson --- specification/trace/tracestate-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 38ffdc4b2b1..4f446f83923 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -36,7 +36,7 @@ key = lcalpha *(lcalpha / DIGIT ) lcalpha = %x61-7A ; a-z ``` -Specific keys used by OTel concerns MUST be defined as part as the Specification too. +Specific keys used by OTel concerns MUST be defined as part as the Specification. ## Value From e1a1298175ab828e2072239993a7c1a890a58816 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 2 Sep 2021 17:17:39 +0200 Subject: [PATCH 16/20] Fix lint. --- specification/trace/tracestate-handling.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 4f446f83923..b91caf5dfb2 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -71,4 +71,3 @@ if err != nil { // Could not set the specified value, traceState was not updated. } ``` - From 7ac0e3c8f75eeae400bde6767803eaf39dafb7f6 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 16 Sep 2021 01:14:36 +0200 Subject: [PATCH 17/20] Apply feedback. --- specification/trace/api.md | 4 +++- specification/trace/tracestate-handling.md | 17 ++++++++++++----- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index d5658197c34..603ffba9142 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -203,7 +203,9 @@ only supports a single flag called [sampled](https://www.w3.org/TR/trace-context `TraceState` carries vendor-specific trace identification data, represented as a list of key-value pairs. TraceState allows multiple tracing systems to participate in the same trace. It is fully described in the [W3C Trace Context -specification](https://www.w3.org/TR/trace-context/#tracestate-header). +specification](https://www.w3.org/TR/trace-context/#tracestate-header). For +specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) +document. The API MUST implement methods to create a `SpanContext`. These methods SHOULD be the only way to create a `SpanContext`. This functionality MUST be fully implemented in the API, and SHOULD NOT be diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index b91caf5dfb2..454409ed127 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -24,6 +24,9 @@ The complete list length MUST NOT exceed 256 characters, as defined by the [TraceState value section](https://www.w3.org/TR/trace-context/#value), and the used keys MUST be unique. +Instrumentation libraries and clients MUST NOT use this entry, and they SHOULD +instead use ther own entry. + ## Key The key is an identifier that describes an OTel concern. @@ -36,7 +39,9 @@ key = lcalpha *(lcalpha / DIGIT ) lcalpha = %x61-7A ; a-z ``` -Specific keys used by OTel concerns MUST be defined as part as the Specification. +Specific keys used by OTel concerns MUST be defined as part as the Specification, +and hence it is forbidden to use to use any key that has not been defined in +the Specification itself. ## Value @@ -60,14 +65,16 @@ in order to preserve existing values belonging to other OTel concerns. For examp if a given concern K wants to set `k1:13`: * `ot=p:8;r:64` will become `ot=p:8;r:64;k1:13`. -* `ot=p:8,r:64;k1:7` will become `ot:p8;r:64;k1:13`. +* `ot=p:8;k1:7;r:64` will become `ot=p8;r:64;k1:13`. Preserving the order is not required. If setting a value ends up making the entire `ot` entry exceed the 256 characters limit, SDKs are advised to abort the operation and signal the user about the error, e.g. ```go -traceState, err := SetTraceStateValue(traceState, value) -if err != nil { - // Could not set the specified value, traceState was not updated. +traceState, ok := SetTraceStateValue(traceState, value) +if ok { + // Successfully set the specified value, traceState was updated. +} else { + // traceState was not updated. } ``` From 7254826aaf79948165a82f03034897adfb2be3ed Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 16 Sep 2021 01:16:28 +0200 Subject: [PATCH 18/20] Fix typo. --- specification/trace/tracestate-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 454409ed127..28e2ac41653 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -25,7 +25,7 @@ The complete list length MUST NOT exceed 256 characters, as defined by the and the used keys MUST be unique. Instrumentation libraries and clients MUST NOT use this entry, and they SHOULD -instead use ther own entry. +instead use their own entry. ## Key From cfafa771ebd5adc5128517cbc7430f6204496c48 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 16 Sep 2021 01:19:08 +0200 Subject: [PATCH 19/20] s/SHOULD/MUST --- specification/trace/tracestate-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 28e2ac41653..6aee73272f0 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -24,7 +24,7 @@ The complete list length MUST NOT exceed 256 characters, as defined by the [TraceState value section](https://www.w3.org/TR/trace-context/#value), and the used keys MUST be unique. -Instrumentation libraries and clients MUST NOT use this entry, and they SHOULD +Instrumentation libraries and clients MUST NOT use this entry, and they MUST instead use their own entry. ## Key From 287bd6894cd04a679616e0f0f22249adeec9b9bd Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 14 Oct 2021 18:58:03 +0200 Subject: [PATCH 20/20] Update specification/trace/tracestate-handling.md Co-authored-by: Joshua MacDonald --- specification/trace/tracestate-handling.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 6aee73272f0..8dd24d45b46 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -13,6 +13,7 @@ a semicolon separated list of key-value pairs such as: * `ot=p:8;r:64` * `ot=foo:bar;k1:13` +The [TraceContext](https://www.w3.org/TR/trace-context/) specification defines support for multiple "tenants" each to use their own `tracestate` entry by prefixing `tenant@` to tenant-specific values in a mixed tracing environment. OpenTelemetry recognizes this syntax but does not specify an interpretation for multi-tenant `tracestate`. The list can be formally defined as: ```