From 71750cde34dd5e4c82cedff6ea847d01ec911375 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 29 Jul 2024 16:22:24 -0700 Subject: [PATCH 01/24] rebase --- CHANGELOG.md | 2 + spec-compliance-matrix.md | 2 + specification/context/api-propagators.md | 12 +++++ specification/trace/api.md | 16 +++---- specification/trace/sdk.md | 56 +++++++++++++++++++++- specification/trace/tracestate-handling.md | 22 +++++++++ 6 files changed, 99 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e71b526382..1635dbc2514 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. ([#4137](https://github.com/open-telemetry/opentelemetry-specification/pull/4137)) - Add in-development `OnEnding` callback to SDK `SpanProcessor` interface. ([#4024](https://github.com/open-telemetry/opentelemetry-specification/pull/4024)) +- Define randomness value requirements for W3C Trace Context Level 2. + ([#4162](https://github.com/open-telemetry/opentelemetry-specification/pull/4162)) ### Metrics diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 374e1e2b340..fc67f7de207 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -87,6 +87,8 @@ formats is required. Implementing more than one format is optional. | [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | + | | + | + | + | + | + | + | + | | | [Attribute Limits](specification/common/README.md#attribute-limits) | X | | + | | + | + | + | + | | | | | | Fetch InstrumentationScope from ReadableSpan | | | + | | + | | | + | | | | | +| TraceID generator implements W3C Trace Context Level 2 randomness | | | | | | | | | | | | | +| OpenTelemetry explicit randomness supported | X | | | | | | | | | | | | ## Baggage diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 257e507c82b..434ff0ad558 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -31,6 +31,7 @@ * [Get Global Propagator](#get-global-propagator) * [Set Global Propagator](#set-global-propagator) - [Propagators Distribution](#propagators-distribution) + * [W3C Trace Context Requirements](#w3c-trace-context-requirements) * [B3 Requirements](#b3-requirements) + [B3 Extract](#b3-extract) + [B3 Inject](#b3-inject) @@ -355,6 +356,17 @@ Additional `Propagator`s implementing vendor-specific protocols such as AWS X-Ray trace header protocol MUST NOT be maintained or distributed as part of the Core OpenTelemetry repositories. +### W3C Trace Context Requirements + +A W3C Trace Context propagator is expected to implement the `traceparent` and `tracestate` contexts fields specified in [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/). + +When injecting and extracting trace context to or from a carrier, the following fields from the `SpanContext` are propagated. + +- TraceID (16 bytes) +- SpanID (8 bytes) +- TraceFlags (8 bits) +- TraceState (string) + ### B3 Requirements B3 has both single and multi-header encodings. It also has semantics that do not diff --git a/specification/trace/api.md b/specification/trace/api.md index b06810ecc53..b2ead38f331 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -244,16 +244,12 @@ non-zero byte. `SpanId` A valid span identifier is an 8-byte array with at least one non-zero byte. -`TraceFlags` contain details about the trace. Unlike TraceState values, -TraceFlags are present in all traces. The current version of the specification -only supports a single flag called [sampled](https://www.w3.org/TR/trace-context/#sampled-flag). - -`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). For -specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) -document. +`TraceFlags` contain details about the trace. Unlike TraceState values, TraceFlags are present in all traces. The current version of the specification supports two flags: + +- [Sampled](https://www.w3.org/TR/trace-context-2/#sampled-flag) +- [Random](https://www.w3.org/TR/trace-context-2/#random-trace-id-flag) + +`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-2/#tracestate-header). For specific OpenTelemetry values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. `IsRemote`, a boolean indicating whether the SpanContext was received from somewhere else or locally generated, see [IsRemote](#isremote). diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 82bec706359..071a9317972 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -23,6 +23,7 @@ linkTitle: SDK - [Sampling](#sampling) * [Recording Sampled reaction table](#recording-sampled-reaction-table) * [SDK Span creation](#sdk-span-creation) + + [Span flags](#span-flags) * [Sampler](#sampler) + [ShouldSample](#shouldsample) + [GetDescription](#getdescription) @@ -33,6 +34,13 @@ linkTitle: SDK - [Requirements for `TraceIdRatioBased` sampler algorithm](#requirements-for-traceidratiobased-sampler-algorithm) + [ParentBased](#parentbased) + [JaegerRemoteSampler](#jaegerremotesampler) + * [Sampling Requirements](#sampling-requirements) + + [TraceID randomness](#traceid-randomness) + + [Random trace flag](#random-trace-flag) + + [Explicit trace randomness](#explicit-trace-randomness) + + [Presumption of TraceID randomness](#presumption-of-traceid-randomness) + + [User-defined explicit trace randomness](#user-defined-explicit-trace-randomness) + + [IdGenerator randomness](#idgenerator-randomness) - [Span Limits](#span-limits) - [Id Generators](#id-generators) - [Span processor](#span-processor) @@ -265,7 +273,7 @@ The OpenTelemetry API has two properties responsible for the data collection: receive them unless the `Sampled` flag was also set. * `Sampled` flag in `TraceFlags` on `SpanContext`. This flag is propagated via the `SpanContext` to child Spans. For more details see the [W3C Trace Context - specification](https://www.w3.org/TR/trace-context/#sampled-flag). This flag indicates that the `Span` has been + specification][W3CCONTEXTSAMPLEDFLAG]. This flag indicates that the `Span` has been `sampled` and will be exported. [Span Exporters](#span-exporter) MUST receive those spans which have `Sampled` flag set to true and they SHOULD NOT receive the ones that do not. @@ -316,6 +324,12 @@ When asked to create a Span, the SDK MUST act as if doing the following in order `Span` is created without an SDK installed or as described in [wrapping a SpanContext in a Span](api.md#wrapping-a-spancontext-in-a-span). +#### Span flags + +The OTLP representation for Span and Span Link include a 32-bit field declared as Span Flags. + +Bits 0-7 of the Span Flags field are reserved for the 8 bits of Trace Context flags, specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. [See the list of recognized flags](./api.md#spancontext). + ### Sampler `Sampler` interface allows users to create custom samplers which will return a @@ -466,6 +480,46 @@ The following configuration properties should be available when creating the sam [jaeger-remote-sampling-api]: https://www.jaegertracing.io/docs/1.41/apis/#remote-sampling-configuration-stable [jaeger-adaptive-sampling]: https://www.jaegertracing.io/docs/1.41/sampling/#adaptive-sampling +### Sampling Requirements + +The [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation includes [a Random trace flag][W3CCONTEXTRANDOMFLAG] for indicating that the TraceID contains 56 random bits, specified for statistical purposes. This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID]. + +Note the Random flag does not propagate through [Trace Context Level 1][W3CCONTEXTLEVEL1] implementations, which do not recognize the flag. Therefore, this flag is considered meaningful only when it is set on a root span context. To enable sampling in this and other situations where TraceIDs lack sufficient randomness, OpenTelemetry defines an optional [explicit randomness value][OTELRVALUE] encoded in the [W3C TraceState field][W3CCONTEXTTRACESTATE]. + +This specification recommends the use of either TraceID randomness or explicit trace randomness, which ensures that samplers always have sufficient randomness when using W3C Trace Context propagation. + +[W3CCONTEXTMAIN]: https://www.w3.org/TR/trace-context-2 +[W3CCONTEXTLEVEL1]: https://www.w3.org/TR/trace-context +[W3CCONTEXTTRACEID]: https://www.w3.org/TR/trace-context-2/#randomness-of-trace-id +[W3CCONTEXTTRACESTATE]: https://www.w3.org/TR/trace-context-2/#tracestate-header +[W3CCONTEXTSAMPLEDFLAG]: https://www.w3.org/TR/trace-context-2/#sampled-flag +[W3CCONTEXTRANDOMFLAG]: https://www.w3.org/TR/trace-context-2/#random-trace-id-flag +[OTELRVALUE]: ./tracestate-handling.md#explicit-randomness-value-rv + +#### TraceID randomness + +The SDK SHOULD implement the TraceID randomness requirements specified in the [W3C Trace Context Level 2][W3CCONTEXTTRACEID] Candidate Recommendation when generating TraceID values. + +#### Random trace flag + +The Trace Context `Random` flag SHOULD be set in the W3C Trace Context instantiated by the SDK when it generates a TraceID meeting the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. + +#### Explicit trace randomness + +When the trace SDK creates a root span context and the TraceID lacks randomness (i.e., the Random flag could not be set), the SDK SHOULD insert explicit randomness using the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. + +#### Presumption of TraceID randomness + +Because explicit randomness values offer a mechanism for sampling TraceIDs without sufficient randomness, OpenTelemetry samplers MUST presume that TraceIDs include sufficient randomness when an explicit randomness value is not present. + +#### User-defined explicit trace randomness + +Trace SDKs SHOULD permit users to setup explicit randomness before creating a root span by entering it into the SpanContext TraceState before creating a root span. This lets users enable consistent sampling across traces. + +#### IdGenerator randomness + +If the SDK uses an `IdGenerator` extension point, the SDK SHOULD enable it to declare whether it meets the Randomness requirement in order to set the random trace flag. + ## Span Limits Span attributes MUST adhere to the [common rules of attribute limits](../common/README.md#attribute-limits). diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index b8486abcd54..4d565ec45a3 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -83,3 +83,25 @@ if ok { // traceState was not updated. } ``` + +## Pre-defined OpenTelemetry sub-keys + +The following values have been defined by OpenTelemetry. + +### Explicit randomness value `rv` + +The OpenTelemetry TraceState `rv` sub-key defines an alternative source of randomness to the use of TraceID randomness when used by samplers decisions. Values of `rv` MUST be exactly 14 hexadecimal digits: + +``` +hexdigit = DIGIT ; A-F ; a-f +``` + +The explicit randomness value is meant to be used instead of extracting randomness from TraceIDs, therefore it contains the same number of bits as a W3C Trace Context Level 2 recommends for TraceIDs. + +Explicit randomness values are meant to propagate through [span contexts](../context/README.md) unmodified. Explicit randomness values SHOULD NOT be erased from the OpenTelemetry TraceState or modified once associated with a new TraceID, so that sampling decisions made using the explicit randomness value are consistent across signals. + +For example, here is a W3C TraceState values including an OpenTelemetry explicit randomness value: + +``` +tracestate: ot=rv:6e6d1a75832a2f +``` From 3c4b8fa5dace773d7c51dca9ba2117b5c4a08f1e Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 30 Jul 2024 07:11:04 -0700 Subject: [PATCH 02/24] line breaks --- specification/trace/api.md | 9 +++++++-- specification/trace/sdk.md | 15 +++++++++++---- specification/trace/tracestate-handling.md | 6 ++++-- 3 files changed, 22 insertions(+), 8 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index b2ead38f331..b8eda2d3a21 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -244,12 +244,17 @@ non-zero byte. `SpanId` A valid span identifier is an 8-byte array with at least one non-zero byte. -`TraceFlags` contain details about the trace. Unlike TraceState values, TraceFlags are present in all traces. The current version of the specification supports two flags: +`TraceFlags` contain details about the trace. +Unlike TraceState values, TraceFlags are present in all traces. +The current version of the specification supports two flags: - [Sampled](https://www.w3.org/TR/trace-context-2/#sampled-flag) - [Random](https://www.w3.org/TR/trace-context-2/#random-trace-id-flag) -`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-2/#tracestate-header). For specific OpenTelemetry values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. +`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-2/#tracestate-header). +For specific OpenTelemetry values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. `IsRemote`, a boolean indicating whether the SpanContext was received from somewhere else or locally generated, see [IsRemote](#isremote). diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 071a9317972..0e8c229cc24 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -328,7 +328,9 @@ When asked to create a Span, the SDK MUST act as if doing the following in order The OTLP representation for Span and Span Link include a 32-bit field declared as Span Flags. -Bits 0-7 of the Span Flags field are reserved for the 8 bits of Trace Context flags, specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. [See the list of recognized flags](./api.md#spancontext). +Bits 0-7 of the Span Flags field are reserved for the 8 bits of Trace Context flags, +specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. +[See the list of recognized flags](./api.md#spancontext). ### Sampler @@ -482,11 +484,16 @@ The following configuration properties should be available when creating the sam ### Sampling Requirements -The [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation includes [a Random trace flag][W3CCONTEXTRANDOMFLAG] for indicating that the TraceID contains 56 random bits, specified for statistical purposes. This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID]. +The [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation includes [a Random trace flag][W3CCONTEXTRANDOMFLAG] for indicating that the TraceID contains 56 random bits, specified for statistical purposes. +This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID]. -Note the Random flag does not propagate through [Trace Context Level 1][W3CCONTEXTLEVEL1] implementations, which do not recognize the flag. Therefore, this flag is considered meaningful only when it is set on a root span context. To enable sampling in this and other situations where TraceIDs lack sufficient randomness, OpenTelemetry defines an optional [explicit randomness value][OTELRVALUE] encoded in the [W3C TraceState field][W3CCONTEXTTRACESTATE]. +Note the Random flag does not propagate through [Trace Context Level 1][W3CCONTEXTLEVEL1] implementations, which do not recognize the flag. +Therefore, this flag is considered meaningful only when it is set on a root span context. +To enable sampling in this and other situations where TraceIDs lack sufficient randomness, +OpenTelemetry defines an optional [explicit randomness value][OTELRVALUE] encoded in the [W3C TraceState field][W3CCONTEXTTRACESTATE]. -This specification recommends the use of either TraceID randomness or explicit trace randomness, which ensures that samplers always have sufficient randomness when using W3C Trace Context propagation. +This specification recommends the use of either TraceID randomness or explicit trace randomness, +which ensures that samplers always have sufficient randomness when using W3C Trace Context propagation. [W3CCONTEXTMAIN]: https://www.w3.org/TR/trace-context-2 [W3CCONTEXTLEVEL1]: https://www.w3.org/TR/trace-context diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 4d565ec45a3..78bf1705344 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -90,7 +90,8 @@ The following values have been defined by OpenTelemetry. ### Explicit randomness value `rv` -The OpenTelemetry TraceState `rv` sub-key defines an alternative source of randomness to the use of TraceID randomness when used by samplers decisions. Values of `rv` MUST be exactly 14 hexadecimal digits: +The OpenTelemetry TraceState `rv` sub-key defines an alternative source of randomness to the use of TraceID randomness when used by samplers decisions. +Values of `rv` MUST be exactly 14 hexadecimal digits: ``` hexdigit = DIGIT ; A-F ; a-f @@ -98,7 +99,8 @@ hexdigit = DIGIT ; A-F ; a-f The explicit randomness value is meant to be used instead of extracting randomness from TraceIDs, therefore it contains the same number of bits as a W3C Trace Context Level 2 recommends for TraceIDs. -Explicit randomness values are meant to propagate through [span contexts](../context/README.md) unmodified. Explicit randomness values SHOULD NOT be erased from the OpenTelemetry TraceState or modified once associated with a new TraceID, so that sampling decisions made using the explicit randomness value are consistent across signals. +Explicit randomness values are meant to propagate through [span contexts](../context/README.md) unmodified. +Explicit randomness values SHOULD NOT be erased from the OpenTelemetry TraceState or modified once associated with a new TraceID, so that sampling decisions made using the explicit randomness value are consistent across signals. For example, here is a W3C TraceState values including an OpenTelemetry explicit randomness value: From c174e36db1262952fab06d32e2c0f739f8ea10dc Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 7 Aug 2024 12:14:15 -0700 Subject: [PATCH 03/24] revise trace randomness requirements for clarity --- specification/trace/sdk.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0e8c229cc24..996bad3d5b0 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -505,27 +505,27 @@ which ensures that samplers always have sufficient randomness when using W3C Tra #### TraceID randomness -The SDK SHOULD implement the TraceID randomness requirements specified in the [W3C Trace Context Level 2][W3CCONTEXTTRACEID] Candidate Recommendation when generating TraceID values. +The SDK SHOULD implement the TraceID randomness requirements of the [W3C Trace Context Level 2][W3CCONTEXTTRACEID] Candidate Recommendation when generating TraceID values for root span contexts. #### Random trace flag -The Trace Context `Random` flag SHOULD be set in the W3C Trace Context instantiated by the SDK when it generates a TraceID meeting the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. +The SDK SHOULD set the `Random` flag in the trace flags of the root span context when it generates TraceIDs that meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. #### Explicit trace randomness -When the trace SDK creates a root span context and the TraceID lacks randomness (i.e., the Random flag could not be set), the SDK SHOULD insert explicit randomness using the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. +The SDK MAY support an optional explicit trace randomness feature. When this option is configured and the trace SDK creates a root span context, the SDK inserts explicit randomness into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. #### Presumption of TraceID randomness -Because explicit randomness values offer a mechanism for sampling TraceIDs without sufficient randomness, OpenTelemetry samplers MUST presume that TraceIDs include sufficient randomness when an explicit randomness value is not present. +OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. #### User-defined explicit trace randomness -Trace SDKs SHOULD permit users to setup explicit randomness before creating a root span by entering it into the SpanContext TraceState before creating a root span. This lets users enable consistent sampling across traces. +Trace SDKs SHOULD permit users to setup explicit randomness by entering it into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] of the context before creating a root span. This lets users have consistent sampling across traces. #### IdGenerator randomness -If the SDK uses an `IdGenerator` extension point, the SDK SHOULD enable it to declare whether it meets the Randomness requirement in order to set the random trace flag. +If the SDK uses an `IdGenerator` extension point, the SDK SHOULD allow the extension to indicate the random trace flag for root span contexts. When an `IdGenerator` instance does not meet the randomness requirements, users can configure explicit randomness instead, otherwise samplers may incorrectly presume TraceID randomness. ## Span Limits From 93dcd7a16a5f391ece1fcf433ccdafef762345e4 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 7 Aug 2024 12:16:43 -0700 Subject: [PATCH 04/24] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks Co-authored-by: Robert Pająk Co-authored-by: Kent Quirk --- specification/context/api-propagators.md | 2 +- specification/trace/tracestate-handling.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index de7193a994f..da7bafecf92 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -358,7 +358,7 @@ the Core OpenTelemetry repositories. ### W3C Trace Context Requirements -A W3C Trace Context propagator is expected to implement the `traceparent` and `tracestate` contexts fields specified in [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/). +A W3C Trace Context propagator MUST parse and set the `traceparent` and `tracestate` HTTP headers as specified in [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/). When injecting and extracting trace context to or from a carrier, the following fields from the `SpanContext` are propagated. diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 78bf1705344..e65b7678ad8 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -102,7 +102,7 @@ The explicit randomness value is meant to be used instead of extracting randomne Explicit randomness values are meant to propagate through [span contexts](../context/README.md) unmodified. Explicit randomness values SHOULD NOT be erased from the OpenTelemetry TraceState or modified once associated with a new TraceID, so that sampling decisions made using the explicit randomness value are consistent across signals. -For example, here is a W3C TraceState values including an OpenTelemetry explicit randomness value: +For example, here is a W3C TraceState value including an OpenTelemetry explicit randomness value: ``` tracestate: ot=rv:6e6d1a75832a2f From 76c6c71424b787a69ff6bc46cb50b5dd98f221cf Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 7 Aug 2024 13:02:14 -0700 Subject: [PATCH 05/24] clarify which contexts for each requirement --- specification/trace/sdk.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 996bad3d5b0..ae860ed74d7 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -505,19 +505,19 @@ which ensures that samplers always have sufficient randomness when using W3C Tra #### TraceID randomness -The SDK SHOULD implement the TraceID randomness requirements of the [W3C Trace Context Level 2][W3CCONTEXTTRACEID] Candidate Recommendation when generating TraceID values for root span contexts. +For root span contexts, the SDK SHOULD implement the TraceID randomness requirements of the [W3C Trace Context Level 2][W3CCONTEXTTRACEID] Candidate Recommendation when generating TraceID values. #### Random trace flag -The SDK SHOULD set the `Random` flag in the trace flags of the root span context when it generates TraceIDs that meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. +For root span contexts, the SDK SHOULD set the `Random` flag in the trace flags when it generates TraceIDs that meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. #### Explicit trace randomness -The SDK MAY support an optional explicit trace randomness feature. When this option is configured and the trace SDK creates a root span context, the SDK inserts explicit randomness into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. +The SDK MAY support an optional explicit trace randomness feature. For root span contexts, when this option is configured, the SDK inserts explicit randomness into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. #### Presumption of TraceID randomness -OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. +For non-root span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. #### User-defined explicit trace randomness From b9ec958489e5df0e255b80475037dacd4fdae633 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 7 Aug 2024 13:57:59 -0700 Subject: [PATCH 06/24] user-defined explicit randomness: may --- specification/trace/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index ae860ed74d7..c455c11aa35 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -517,11 +517,11 @@ The SDK MAY support an optional explicit trace randomness feature. For root spa #### Presumption of TraceID randomness -For non-root span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. +For all span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. #### User-defined explicit trace randomness -Trace SDKs SHOULD permit users to setup explicit randomness by entering it into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] of the context before creating a root span. This lets users have consistent sampling across traces. +Trace SDKs MAY permit users to setup explicit randomness by entering it into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] of the context before creating a root span. This lets users have consistent sampling across traces. #### IdGenerator randomness From 6a2d6c5087f86bd4ad2352daaf2449c25a9cb4e9 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 7 Aug 2024 13:58:11 -0700 Subject: [PATCH 07/24] lowercase hex only --- specification/trace/tracestate-handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index e65b7678ad8..48701392a7b 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -91,10 +91,10 @@ The following values have been defined by OpenTelemetry. ### Explicit randomness value `rv` The OpenTelemetry TraceState `rv` sub-key defines an alternative source of randomness to the use of TraceID randomness when used by samplers decisions. -Values of `rv` MUST be exactly 14 hexadecimal digits: +Values of `rv` MUST be exactly 14 lower-case hexadecimal digits: ``` -hexdigit = DIGIT ; A-F ; a-f +hexdigit = DIGIT ; a-f ``` The explicit randomness value is meant to be used instead of extracting randomness from TraceIDs, therefore it contains the same number of bits as a W3C Trace Context Level 2 recommends for TraceIDs. From 56d8e264a9746773a154da42c24cc7ceafa2e14d Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 12 Sep 2024 10:15:27 -0700 Subject: [PATCH 08/24] Clarify when tracestate and traceparent are propagated --- specification/context/api-propagators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index da7bafecf92..0c3c1920d70 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -358,14 +358,14 @@ the Core OpenTelemetry repositories. ### W3C Trace Context Requirements -A W3C Trace Context propagator MUST parse and set the `traceparent` and `tracestate` HTTP headers as specified in [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/). +A W3C Trace Context propagator MUST parse and validate the `traceparent` and `tracestate` HTTP headers as specified in [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/). A W3C Trace Context propagator MUST propagate a valid `traceparent` value using the same header. A W3C Trace Context propagator MUST propagate a valid `tracestate` unless the value is empty, in which case the `tracestate` header may be omitted. When injecting and extracting trace context to or from a carrier, the following fields from the `SpanContext` are propagated. - TraceID (16 bytes) - SpanID (8 bytes) - TraceFlags (8 bits) -- TraceState (string) +- TraceState (string, unless empty) ### B3 Requirements From 748991497345660a35836321e31a568f8322fca9 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 12 Sep 2024 10:19:56 -0700 Subject: [PATCH 09/24] tracing-system-specific, not vendor --- 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 8c7bfbcb4af..0702e15855b 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -251,7 +251,7 @@ The current version of the specification supports two flags: - [Sampled](https://www.w3.org/TR/trace-context-2/#sampled-flag) - [Random](https://www.w3.org/TR/trace-context-2/#random-trace-id-flag) -`TraceState` carries vendor-specific trace identification data, represented as a list of key-value pairs. +`TraceState` carries tracing-system-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-2/#tracestate-header). For specific OpenTelemetry values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. From 6ad9842ac125c3bf9b1064a9b828344b3bc524c7 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 12 Sep 2024 10:37:34 -0700 Subject: [PATCH 10/24] idgenerator randomness --- specification/trace/sdk.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 51572c22670..531ad49a5a8 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -488,7 +488,7 @@ The [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation include This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID]. Note the Random flag does not propagate through [Trace Context Level 1][W3CCONTEXTLEVEL1] implementations, which do not recognize the flag. -Therefore, this flag is considered meaningful only when it is set on a root span context. +When this flag is 1, it is considered meaningful. When this flag is 0, it may be due to a non-random TraceID or because a Trace Context Level 1 propagator was used. To enable sampling in this and other situations where TraceIDs lack sufficient randomness, OpenTelemetry defines an optional [explicit randomness value][OTELRVALUE] encoded in the [W3C TraceState field][W3CCONTEXTTRACESTATE]. @@ -584,6 +584,10 @@ an interface like the java example below (name of the interface MAY be [SpanContext](./api.md#retrieving-the-traceid-and-spanid)), which provides extension points for two methods, one to generate a `SpanId` and one for `TraceId`. +Custom implementations of the `IdGenerator` SHOULD support setting the +W3C Trace Context `random` flag when generated TraceID values meet the +[W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. + ```java public interface IdGenerator { byte[] generateSpanIdBytes(); From 47d3132f7bce06064dd867419fedb611598a7c36 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 12 Sep 2024 10:42:15 -0700 Subject: [PATCH 11/24] marker interface --- specification/trace/sdk.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 531ad49a5a8..de81dadca93 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -584,10 +584,6 @@ an interface like the java example below (name of the interface MAY be [SpanContext](./api.md#retrieving-the-traceid-and-spanid)), which provides extension points for two methods, one to generate a `SpanId` and one for `TraceId`. -Custom implementations of the `IdGenerator` SHOULD support setting the -W3C Trace Context `random` flag when generated TraceID values meet the -[W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID]. - ```java public interface IdGenerator { byte[] generateSpanIdBytes(); @@ -595,6 +591,13 @@ public interface IdGenerator { } ``` +Custom implementations of the `IdGenerator` SHOULD support setting the +W3C Trace Context `random` flag when all generated TraceID values meet +the [W3C Trace Context Level 2 randomness +requirements][W3CCONTEXTTRACEID]. This is presumed to be a static +property of the `IdGenerator` implementation which can be inferred +using language features, for example by extending a marker interface. + Additional `IdGenerator` implementing vendor-specific protocols such as AWS X-Ray trace id generator MUST NOT be maintained or distributed as part of the Core OpenTelemetry repositories. From bfa4ca21ea2a89f418c14de18071f51dc686dfed Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 12 Sep 2024 10:44:25 -0700 Subject: [PATCH 12/24] changelog fix --- CHANGELOG.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c1c781f7690..f0a4f028f74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,10 +11,6 @@ release. ### Traces -- Remove restriction that sampler description is immutable. - ([#4137](https://github.com/open-telemetry/opentelemetry-specification/pull/4137)) -- Add in-development `OnEnding` callback to SDK `SpanProcessor` interface. - ([#4024](https://github.com/open-telemetry/opentelemetry-specification/pull/4024)) - Minor clarification on BatchExportingProcessor behavior. ([#4164](https://github.com/open-telemetry/opentelemetry-specification/pull/4164)) - Clarify `SpanKind` description, extend it to cover links, add examples of From 71655966bc077995310288280a3ee0c093532a6a Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 2 Oct 2024 15:50:42 -0700 Subject: [PATCH 13/24] 2 revisions --- specification/trace/sdk.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index de81dadca93..976775eda29 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -308,10 +308,9 @@ When asked to create a Span, the SDK MUST act as if doing the following in order 1. If there is a valid parent trace ID, use it. Otherwise generate a new trace ID (note: this must be done before calling `ShouldSample`, because it expects a valid trace ID as input). -2. Query the `Sampler`'s [`ShouldSample`](#shouldsample) method - (Note that the [built-in `ParentBasedSampler`](#parentbased) can be used to - use the sampling decision of the parent, - translating a set SampledFlag to RECORD and an unset one to DROP). +2. Query the `Sampler`'s [`ShouldSample`](#shouldsample) method. + The [built-in `ParentBasedSampler`](#parentbased) can be used to + take the sampling decision of the parent context using the `Sampled` flag. 3. Generate a new span ID for the `Span`, independently of the sampling decision. This is done so other components (such as logs or exception handling) can rely on a unique span ID, even if the `Span` is a non-recording instance. @@ -326,7 +325,7 @@ When asked to create a Span, the SDK MUST act as if doing the following in order #### Span flags -The OTLP representation for Span and Span Link include a 32-bit field declared as Span Flags. +The OTLP representation for Span and Span Link includes a 32-bit field declared as Span Flags. Bits 0-7 of the Span Flags field are reserved for the 8 bits of Trace Context flags, specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. From a6a4d1147968dd96b2f9a4a816650551c8cf90b3 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 2 Oct 2024 16:36:46 -0700 Subject: [PATCH 14/24] spec is optional --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 3d0a1b638cd..d0de6cc3f16 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -87,7 +87,7 @@ formats is required. Implementing more than one format is optional. | [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | + | | + | + | + | + | + | + | + | | | [Attribute Limits](specification/common/README.md#attribute-limits) | X | | + | | + | + | + | + | | | | | | Fetch InstrumentationScope from ReadableSpan | | | + | | + | | | + | | | | | -| TraceID generator implements W3C Trace Context Level 2 randomness | | | | | | | | | | | | | +| TraceID generator implements W3C Trace Context Level 2 randomness | X | | | | | | | | | | | | | OpenTelemetry explicit randomness supported | X | | | | | | | | | | | | ## Baggage From 140492b95b3cdb5b39174e1e8fd9d70b65ca0f27 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 2 Oct 2024 16:49:57 -0700 Subject: [PATCH 15/24] API for explicit trace randomness --- specification/trace/api.md | 3 +++ specification/trace/sdk.md | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 21b0198617d..0e76db18e46 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -414,6 +414,9 @@ trace. A span is said to be a *root span* if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace. Implementations MUST provide an option to create a `Span` as a root span, and MUST generate a new `TraceId` for each root span created. +Implementations MAY support an option to set the `TraceState` of new +root spans, otherwise root span contexts have the empty `TraceState` set. + For a Span with a parent, the `TraceId` MUST be the same as the parent. Also, the child span MUST inherit all `TraceState` values of its parent by default. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 6754c545f42..e12ce93a56e 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -512,7 +512,7 @@ For root span contexts, the SDK SHOULD set the `Random` flag in the trace flags #### Explicit trace randomness -The SDK MAY support an optional explicit trace randomness feature. For root span contexts, when this option is configured, the SDK inserts explicit randomness into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. +The SDK MAY support an optional explicit trace randomness feature. For root span contexts, when this option is configured, the SDK inserts explicit randomness into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. Explicit trace randomness can be the result of a custom IdGenerator that does not meet the TraceID randomness requirement, or through user-defined explicit trace randomness. #### Presumption of TraceID randomness @@ -522,6 +522,8 @@ For all span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet Trace SDKs MAY permit users to setup explicit randomness by entering it into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] of the context before creating a root span. This lets users have consistent sampling across traces. +SDK support means permitting the user to set the `TraceState` of a root span, in particular so that the OpenTelemetry TraceState `rv` sub-key passes through to the root span Sampler. + #### IdGenerator randomness If the SDK uses an `IdGenerator` extension point, the SDK SHOULD allow the extension to indicate the random trace flag for root span contexts. When an `IdGenerator` instance does not meet the randomness requirements, users can configure explicit randomness instead, otherwise samplers may incorrectly presume TraceID randomness. From c684e61cead2aac166cb53946363e57477e0c167 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 3 Oct 2024 13:31:00 -0700 Subject: [PATCH 16/24] revert chlog --- CHANGELOG.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e7563b8b096..0b0ac26e964 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,11 +11,6 @@ release. ### Traces -- Minor clarification on BatchExportingProcessor behavior. - ([#4164](https://github.com/open-telemetry/opentelemetry-specification/pull/4164)) -- Clarify `SpanKind` description, extend it to cover links, add examples of - nested client spans. - ([#4178](https://github.com/open-telemetry/opentelemetry-specification/pull/4178)) - Make all fields as identifying for Tracer. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) - Clarify that `Export` MUST NOT be called by simple and batching processors concurrently. From d92643b1866fb691fc65cac0e9841196be8ee0b2 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 3 Oct 2024 15:37:07 -0700 Subject: [PATCH 17/24] revise to limit explicit randomness difficulty --- spec-compliance-matrix.md | 2 +- specification/trace/api.md | 3 --- specification/trace/sdk.md | 17 +++++++++-------- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index d0de6cc3f16..0f0ca1f8b55 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -88,7 +88,7 @@ formats is required. Implementing more than one format is optional. | [Attribute Limits](specification/common/README.md#attribute-limits) | X | | + | | + | + | + | + | | | | | | Fetch InstrumentationScope from ReadableSpan | | | + | | + | | | + | | | | | | TraceID generator implements W3C Trace Context Level 2 randomness | X | | | | | | | | | | | | -| OpenTelemetry explicit randomness supported | X | | | | | | | | | | | | +| OpenTelemetry explicit randomness inserted for non-random IdGenerators | X | | | | | | | | | | | | ## Baggage diff --git a/specification/trace/api.md b/specification/trace/api.md index 0e76db18e46..21b0198617d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -414,9 +414,6 @@ trace. A span is said to be a *root span* if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace. Implementations MUST provide an option to create a `Span` as a root span, and MUST generate a new `TraceId` for each root span created. -Implementations MAY support an option to set the `TraceState` of new -root spans, otherwise root span contexts have the empty `TraceState` set. - For a Span with a parent, the `TraceId` MUST be the same as the parent. Also, the child span MUST inherit all `TraceState` values of its parent by default. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index e12ce93a56e..712185e75c0 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -512,21 +512,22 @@ For root span contexts, the SDK SHOULD set the `Random` flag in the trace flags #### Explicit trace randomness -The SDK MAY support an optional explicit trace randomness feature. For root span contexts, when this option is configured, the SDK inserts explicit randomness into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. Explicit trace randomness can be the result of a custom IdGenerator that does not meet the TraceID randomness requirement, or through user-defined explicit trace randomness. +For root span contexts, the when the SDK generates a TraceID that does not meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], and when the initial `TraceState` does not already define the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE], the SDK SHOULD insert an explicit trace randomness value into the OpenTelemetry TraceState value containing 56 random bits. -#### Presumption of TraceID randomness - -For all span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. +For example, here's a W3C Trace Context with non-random identifiers and an explicit randomness value: -#### User-defined explicit trace randomness +``` +traceparent: 00-ffffffffffffffffffffffffffffffff-ffffffffffffffff-00 +tracestate: ot=rv:7479cfb506891d +``` -Trace SDKs MAY permit users to setup explicit randomness by entering it into the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] of the context before creating a root span. This lets users have consistent sampling across traces. +#### Presumption of TraceID randomness -SDK support means permitting the user to set the `TraceState` of a root span, in particular so that the OpenTelemetry TraceState `rv` sub-key passes through to the root span Sampler. +For all span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet the W3C Trace Context Level 2 randomness requirements, unless an explicit randomness value is present in the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. #### IdGenerator randomness -If the SDK uses an `IdGenerator` extension point, the SDK SHOULD allow the extension to indicate the random trace flag for root span contexts. When an `IdGenerator` instance does not meet the randomness requirements, users can configure explicit randomness instead, otherwise samplers may incorrectly presume TraceID randomness. +If the SDK uses an `IdGenerator` extension point, the SDK SHOULD allow the extension to determine whether the Random flag is set when new IDs are generated. When an `IdGenerator` instance does not meet the randomness requirements, the SDK SHOULD insert explicit randomness instead, otherwise samplers will incorrectly presume TraceID randomness. ## Span Limits From b98a4d002ec674dbf05446fd3a6271d9a8ad0e25 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Fri, 4 Oct 2024 14:21:13 -0700 Subject: [PATCH 18/24] toc --- specification/trace/sdk.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 712185e75c0..5963786fb75 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -39,7 +39,6 @@ linkTitle: SDK + [Random trace flag](#random-trace-flag) + [Explicit trace randomness](#explicit-trace-randomness) + [Presumption of TraceID randomness](#presumption-of-traceid-randomness) - + [User-defined explicit trace randomness](#user-defined-explicit-trace-randomness) + [IdGenerator randomness](#idgenerator-randomness) - [Span Limits](#span-limits) - [Id Generators](#id-generators) From 6b53a204429c89acee606c3dc12ac53b14f53274 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 21 Oct 2024 09:06:13 -0700 Subject: [PATCH 19/24] Apply suggestions from code review Co-authored-by: Trask Stalnaker --- specification/trace/sdk.md | 4 ++-- specification/trace/tracestate-handling.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 44016a123c6..cf0780438cb 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -326,7 +326,7 @@ When asked to create a Span, the SDK MUST act as if doing the following in order The OTLP representation for Span and Span Link includes a 32-bit field declared as Span Flags. -Bits 0-7 of the Span Flags field are reserved for the 8 bits of Trace Context flags, +Bits 0-7 (8 least significant bits) of the Span Flags field are reserved for the 8 bits of Trace Context flags, specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. [See the list of recognized flags](./api.md#spancontext). @@ -511,7 +511,7 @@ For root span contexts, the SDK SHOULD set the `Random` flag in the trace flags #### Explicit trace randomness -For root span contexts, the when the SDK generates a TraceID that does not meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], and when the initial `TraceState` does not already define the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE], the SDK SHOULD insert an explicit trace randomness value into the OpenTelemetry TraceState value containing 56 random bits. +For root span contexts, when the SDK generates a TraceID that does not meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], and when the initial `TraceState` does not already define the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE], the SDK SHOULD insert an explicit trace randomness value into the OpenTelemetry TraceState value containing 56 random bits. For example, here's a W3C Trace Context with non-random identifiers and an explicit randomness value: diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index 48701392a7b..88de6a354e5 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -97,7 +97,7 @@ Values of `rv` MUST be exactly 14 lower-case hexadecimal digits: hexdigit = DIGIT ; a-f ``` -The explicit randomness value is meant to be used instead of extracting randomness from TraceIDs, therefore it contains the same number of bits as a W3C Trace Context Level 2 recommends for TraceIDs. +The explicit randomness value is meant to be used instead of extracting randomness from TraceIDs, therefore it contains the same number of bits as W3C Trace Context Level 2 recommends for TraceIDs. Explicit randomness values are meant to propagate through [span contexts](../context/README.md) unmodified. Explicit randomness values SHOULD NOT be erased from the OpenTelemetry TraceState or modified once associated with a new TraceID, so that sampling decisions made using the explicit randomness value are consistent across signals. From 1c07f763a7c7298b655f07fa22cea33527967a04 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 21 Oct 2024 09:18:37 -0700 Subject: [PATCH 20/24] Status: development; reword IdGenerator randomness requirement --- specification/trace/sdk.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 44016a123c6..6aea3d2bb23 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -482,6 +482,8 @@ The following configuration properties should be available when creating the sam ### Sampling Requirements +**Status**: [Development](../document-status.md) + The [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation includes [a Random trace flag][W3CCONTEXTRANDOMFLAG] for indicating that the TraceID contains 56 random bits, specified for statistical purposes. This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID]. @@ -592,17 +594,22 @@ public interface IdGenerator { } ``` -Custom implementations of the `IdGenerator` SHOULD support setting the -W3C Trace Context `random` flag when all generated TraceID values meet -the [W3C Trace Context Level 2 randomness -requirements][W3CCONTEXTTRACEID]. This is presumed to be a static -property of the `IdGenerator` implementation which can be inferred -using language features, for example by extending a marker interface. - Additional `IdGenerator` implementing vendor-specific protocols such as AWS X-Ray trace id generator MUST NOT be maintained or distributed as part of the Core OpenTelemetry repositories. +### IdGenerator randomness + +**Status**: [Development](../document-status.md) + +Custom implementations of the `IdGenerator` SHOULD identify themselves +appropriately when all generated TraceID values meet the [W3C Trace +Context Level 2 randomness requirements][W3CCONTEXTTRACEID], so that +the Trace `random` flag will be set in the associated Trace contexts. +This is presumed to be a static property of the `IdGenerator` +implementation which can be inferred using language features, for +example by extending a marker interface. + ## Span processor Span processor is an interface which allows hooks for span start and end method From 61ad71c895335937d5fb103490353d3223281c7a Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 21 Oct 2024 11:42:26 -0700 Subject: [PATCH 21/24] clarify alternate SDK requirements --- specification/trace/sdk.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0367e8868b1..0f1781921aa 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -513,9 +513,29 @@ For root span contexts, the SDK SHOULD set the `Random` flag in the trace flags #### Explicit trace randomness -For root span contexts, when the SDK generates a TraceID that does not meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], and when the initial `TraceState` does not already define the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE], the SDK SHOULD insert an explicit trace randomness value into the OpenTelemetry TraceState value containing 56 random bits. +Explicit trace randomness is a mechanism that enables API users and +SDK authors to control trace randomness. The following recommendation +applies to Trace SDKs that have disregarded the recommendation on +TraceID randomness, above. It has two parts. -For example, here's a W3C Trace Context with non-random identifiers and an explicit randomness value: +##### Do not overwrite explicit trace randomness + +API users control the initial TraceState of a root span, so they can +provide explicit trace randomness for a trace by defining the [`rv` +sub-key of the OpenTelemetry TraceState][OTELRVALUE]. SDKs MUST NOT +overwrite explicit trace randomness in an OpenTelemetry TraceState +value. + +##### Set explicit trace randomness for non-random TraceIDs + +For root span contexts, when the SDK generates a TraceID that does not +meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], +and when the the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] is +not already set, the SDK SHOULD insert an explicit trace randomness value +into the OpenTelemetry TraceState value containing 56 random bits. + +For example, here's a W3C Trace Context with non-random identifiers and an +explicit randomness value: ``` traceparent: 00-ffffffffffffffffffffffffffffffff-ffffffffffffffff-00 From ba7114e41167b396561c38f883fc3dc5afc484dc Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 21 Oct 2024 11:57:22 -0700 Subject: [PATCH 22/24] whitespace --- specification/trace/sdk.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0f1781921aa..98ab00af90d 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -38,10 +38,13 @@ linkTitle: SDK + [TraceID randomness](#traceid-randomness) + [Random trace flag](#random-trace-flag) + [Explicit trace randomness](#explicit-trace-randomness) + - [Do not overwrite explicit trace randomness](#do-not-overwrite-explicit-trace-randomness) + - [Set explicit trace randomness for non-random TraceIDs](#set-explicit-trace-randomness-for-non-random-traceids) + [Presumption of TraceID randomness](#presumption-of-traceid-randomness) + [IdGenerator randomness](#idgenerator-randomness) - [Span Limits](#span-limits) - [Id Generators](#id-generators) + * [IdGenerator randomness](#idgenerator-randomness-1) - [Span processor](#span-processor) * [Interface definition](#interface-definition) + [OnStart](#onstart) @@ -523,15 +526,15 @@ TraceID randomness, above. It has two parts. API users control the initial TraceState of a root span, so they can provide explicit trace randomness for a trace by defining the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE]. SDKs MUST NOT -overwrite explicit trace randomness in an OpenTelemetry TraceState +overwrite explicit trace randomness in an OpenTelemetry TraceState value. ##### Set explicit trace randomness for non-random TraceIDs -For root span contexts, when the SDK generates a TraceID that does not +For root span contexts, when the SDK generates a TraceID that does not meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], -and when the the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] is -not already set, the SDK SHOULD insert an explicit trace randomness value +and when the the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] is +not already set, the SDK SHOULD insert an explicit trace randomness value into the OpenTelemetry TraceState value containing 56 random bits. For example, here's a W3C Trace Context with non-random identifiers and an From b75113ceb691b7658bf81f7b2e6bd6ef1216b143 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 30 Oct 2024 15:08:58 -0700 Subject: [PATCH 23/24] From Peter's feedback: Root samplers MAY set explicit randomness. SDKs are not required to. Built-in samplers are not required to. --- specification/trace/sdk.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 98ab00af90d..1b81a1fe187 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -525,17 +525,21 @@ TraceID randomness, above. It has two parts. API users control the initial TraceState of a root span, so they can provide explicit trace randomness for a trace by defining the [`rv` -sub-key of the OpenTelemetry TraceState][OTELRVALUE]. SDKs MUST NOT -overwrite explicit trace randomness in an OpenTelemetry TraceState +sub-key of the OpenTelemetry TraceState][OTELRVALUE]. SDKs and Samplers +MUST NOT overwrite explicit trace randomness in an OpenTelemetry TraceState value. -##### Set explicit trace randomness for non-random TraceIDs +##### Root samplers set explicit trace randomness for non-random TraceIDs -For root span contexts, when the SDK generates a TraceID that does not -meet the [W3C Trace Context Level 2 randomness requirements][W3CCONTEXTTRACEID], -and when the the [`rv` sub-key of the OpenTelemetry TraceState][OTELRVALUE] is -not already set, the SDK SHOULD insert an explicit trace randomness value -into the OpenTelemetry TraceState value containing 56 random bits. +When the SDK has generated a TraceID that does not meet the [W3C Trace +Context Level 2 randomness requirements][W3CCONTEXTTRACEID], indicated +by an unset trace random flag, and when the the [`rv` sub-key of the +OpenTelemetry TraceState][OTELRVALUE] is not already set, the Root +sampler has the opportunity to insert explicit trace randomness. + +Root Samplers MAY insert an explicit trace randomness value into the +OpenTelemetry TraceState value in cases where an explicit trace +randomness value is not already set. For example, here's a W3C Trace Context with non-random identifiers and an explicit randomness value: @@ -551,7 +555,7 @@ For all span contexts, OpenTelemetry samplers SHOULD presume that TraceIDs meet #### IdGenerator randomness -If the SDK uses an `IdGenerator` extension point, the SDK SHOULD allow the extension to determine whether the Random flag is set when new IDs are generated. When an `IdGenerator` instance does not meet the randomness requirements, the SDK SHOULD insert explicit randomness instead, otherwise samplers will incorrectly presume TraceID randomness. +If the SDK uses an `IdGenerator` extension point, the SDK SHOULD allow the extension to determine whether the Random flag is set when new IDs are generated. ## Span Limits From 0ed30ef21396a3ef1b4aeeca16f3d21c0cf191ea Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 13 Nov 2024 14:34:28 -0800 Subject: [PATCH 24/24] editorial --- spec-compliance-matrix.md | 2 +- specification/trace/sdk.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 24666b14995..4abce1579c2 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -88,7 +88,7 @@ formats is required. Implementing more than one format is optional. | [Attribute Limits](specification/common/README.md#attribute-limits) | X | | + | | + | + | + | + | | | | | | Fetch InstrumentationScope from ReadableSpan | | | + | | + | | | + | | | | | | TraceID generator implements W3C Trace Context Level 2 randomness | X | | | | | | | | | | | | -| OpenTelemetry explicit randomness inserted for non-random IdGenerators | X | | | | | | | | | | | | + ## Baggage diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 1b81a1fe187..bdf04b4c362 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -311,8 +311,6 @@ When asked to create a Span, the SDK MUST act as if doing the following in order (note: this must be done before calling `ShouldSample`, because it expects a valid trace ID as input). 2. Query the `Sampler`'s [`ShouldSample`](#shouldsample) method. - The [built-in `ParentBasedSampler`](#parentbased) can be used to - take the sampling decision of the parent context using the `Sampled` flag. 3. Generate a new span ID for the `Span`, independently of the sampling decision. This is done so other components (such as logs or exception handling) can rely on a unique span ID, even if the `Span` is a non-recording instance.