From 71750cde34dd5e4c82cedff6ea847d01ec911375 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 29 Jul 2024 16:22:24 -0700 Subject: [PATCH] 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 +```