Update Trace specification to use W3C Trace Context Level 2; add Random flag

CHANGELOG.md

@@ -11,6 +11,11 @@ release.
 
 ### Traces
 
+- Specify how span flags, trace context flags, and the tracestate
+  field are propagated and exported by trace SDKs in the W3C Trace
+  Context Level 2
+  specification. ([#3924](https://github.com/open-telemetry/opentelemetry-specification/pull/3924))
+
 ### Metrics
 
 - Clarify that exemplar reservoir default may change in a minor version.

spec-compliance-matrix.md

@@ -37,7 +37,8 @@ formats is required. Implementing more than one format is optional.
 | [SpanContext](specification/trace/api.md#spancontext)                                            |          |     |      |     |        |      |        |     |      |     |      |       |
 | IsValid                                                                                          |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | IsRemote                                                                                         |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
-| Conforms to the W3C TraceContext spec                                                            |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
+| Conforms to the W3C Level 1 TraceContext spec                                                    |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
+| Conforms to the W3C Level 2 TraceContext spec                                                    |          |     |      |     |        |      |        |     |      |     |      |       |
 | [Span](specification/trace/api.md#span)                                                          | Optional | Go  | Java | JS  | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
 | Create root span                                                                                 |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | Create with default parent (active span)                                                         |          | N/A | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |

specification/configuration/sdk-environment-variables.md

@@ -97,7 +97,7 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
 
 Known values for `OTEL_PROPAGATORS` are:
 
-- `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context/)
+- `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context-2/)
 - `"baggage"`: [W3C Baggage](https://www.w3.org/TR/baggage/)
 - `"b3"`: [B3 Single](../context/api-propagators.md#configuration)
 - `"b3multi"`: [B3 Multi](../context/api-propagators.md#configuration)

specification/context/api-propagators.md

@@ -355,6 +355,26 @@ 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` context 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 are propagated.
+
+- TraceID (16 bytes)
+- SpanID (8 bytes)
+- TraceFlags (8 bits)
+- TraceState (string)
+
+There are two trace flag values defined in W3C Trace Context Level 2
+specification, `Sampled` (0x1) and `Random` (0x2).  Propagators need to
+set bits 2-7 of the Trace Flags (6 most significant bits) to zero, as
+they are reserved for future use and the W3C specification requires
+participants to set them to zero.
+
 ### B3 Requirements
 
 B3 has both single and multi-header encodings. It also has semantics that do not

specification/logs/data-model.md

@@ -224,7 +224,7 @@ timestamp internally the following logic is recommended:
 Type: byte sequence.
 
 Description: Request trace id as defined in
-[W3C Trace Context](https://www.w3.org/TR/trace-context/#trace-id). Can be set
+[W3C Trace Context](https://www.w3.org/TR/trace-context-2/#trace-id). Can be set
 for logs that are part of request processing and have an assigned trace id. This
 field is optional.
 
@@ -241,7 +241,7 @@ is optional.
 Type: byte.
 
 Description: Trace flag as defined in
-[W3C Trace Context](https://www.w3.org/TR/trace-context/#trace-flags)
+[W3C Trace Context](https://www.w3.org/TR/trace-context-2/#trace-flags)
 specification. At the time of writing the specification defines one flag - the
 SAMPLED flag. This field is optional.
 

specification/overview.md

@@ -187,7 +187,7 @@ propagated from parent to child **Spans**.
 - **Tracestate** carries tracing-system specific context in a list of key value
   pairs. **Tracestate** allows different vendors propagate additional
   information and inter-operate with their legacy Id formats. For more details
-  see [this](https://www.w3.org/TR/trace-context/#tracestate-header).
+  see [this](https://www.w3.org/TR/trace-context-2/#tracestate-header).
 
 ### Links between spans
 

specification/trace/api.md

@@ -209,7 +209,7 @@ A `SpanContext` represents the portion of a `Span` which must be serialized and
 propagated along side of a distributed context. `SpanContext`s are immutable.
 
 The OpenTelemetry `SpanContext` representation conforms to the [W3C TraceContext
-specification](https://www.w3.org/TR/trace-context/). It contains two
+specification](https://www.w3.org/TR/trace-context-2/). It contains two
 identifiers - a `TraceId` and a `SpanId` - along with a set of common
 `TraceFlags` and system-specific `TraceState` values.
 
@@ -220,13 +220,16 @@ non-zero byte.
 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).
+TraceFlags are present in all traces. The Level 2 version of the W3C Trace Context
+specification defines 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/#tracestate-header). For
+specification](https://www.w3.org/TR/trace-context-2/#tracestate-header). For
 specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md)
 document.
 
@@ -264,17 +267,17 @@ When extracting a `SpanContext` through the [Propagators API](../context/api-pro
 ### TraceState
 
 `TraceState` is a part of [`SpanContext`](./api.md#spancontext), represented by an immutable list of string key/value pairs and
-formally defined by the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header).
+formally defined by the [W3C Trace Context specification](https://www.w3.org/TR/trace-context-2/#tracestate-header).
 Tracing API MUST provide at least the following operations on `TraceState`:
 
 * Get value for a given key
 * Add a new key/value pair
 * Update an existing value for a given key
 * Delete a key/value pair
 
-These operations MUST follow the rules described in the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#mutating-the-tracestate-field).
+These operations MUST follow the rules described in the [W3C Trace Context specification](https://www.w3.org/TR/trace-context-2/#mutating-the-tracestate-field).
 All mutating operations MUST return a new `TraceState` with the modifications applied.
-`TraceState` MUST at all times be valid according to rules specified in [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header-field-values).
+`TraceState` MUST at all times be valid according to rules specified in [W3C Trace Context specification](https://www.w3.org/TR/trace-context-2/#tracestate-header-field-values).
 Every mutating operations MUST validate input parameters.
 If invalid value is passed the operation MUST NOT return `TraceState` containing invalid data
 and MUST follow the [general error handling guidelines](../error-handling.md).

specification/trace/sdk.md

@@ -193,7 +193,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](https://www.w3.org/TR/trace-context-2/#sampled-flag). 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.

specification/trace/tracestate-handling.md

@@ -6,8 +6,8 @@ linkTitle: TraceState
 
 **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),
+In alignment to the [TraceContext](https://www.w3.org/TR/trace-context-2/) specification, this section uses the
+Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context-2/#bib-rfc5234),
 including the DIGIT rule in that document.
 
 When setting [TraceState](api.md#tracestate) values that are part of the OTel ecosystem,
@@ -17,7 +17,7 @@ a semicolon separated list of key-value pairs such as:
 * `ot=p:8;r:62`
 * `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 [TraceContext](https://www.w3.org/TR/trace-context-2/) 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:
 
 ```
@@ -26,7 +26,7 @@ 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),
+[TraceState value section](https://www.w3.org/TR/trace-context-2/#value),
 and the used keys MUST be unique.
 
 Instrumentation libraries and clients MUST NOT use this entry, and they MUST

specification/trace/tracestate-probability-sampling.md

@@ -435,7 +435,7 @@ tracestate: ot=r:3;p:2
 ```
 
 The `traceparent` contents in this example example are repeated from
-the [W3C specification](https://www.w3.org/TR/trace-context/#examples-of-http-traceparent-headers))
+the [W3C specification](https://www.w3.org/TR/trace-context-2/#examples-of-http-traceparent-headers))
 and have the following base64-encoded field values:
 
 ```