You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -377,6 +378,17 @@ Additional `Propagator`s implementing vendor-specific protocols such as AWS
377
378
X-Ray trace header protocol MUST NOT be maintained or distributed as part of
378
379
the Core OpenTelemetry repositories.
379
380
381
+
### W3C Trace Context Requirements
382
+
383
+
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.
384
+
385
+
When injecting and extracting trace context to or from a carrier, the following fields from the `SpanContext` are propagated.
386
+
387
+
- TraceID (16 bytes)
388
+
- SpanID (8 bytes)
389
+
- TraceFlags (8 bits)
390
+
- TraceState (string, unless empty)
391
+
380
392
### B3 Requirements
381
393
382
394
B3 has both single and multi-header encodings. It also has semantics that do not
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.
487
+
This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID].
488
+
489
+
Note the Random flag does not propagate through [Trace Context Level 1][W3CCONTEXTLEVEL1] implementations, which do not recognize the flag.
490
+
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.
491
+
To enable sampling in this and other situations where TraceIDs lack sufficient randomness,
492
+
OpenTelemetry defines an optional [explicit randomness value][OTELRVALUE] encoded in the [W3C TraceState field][W3CCONTEXTTRACESTATE].
493
+
494
+
This specification recommends the use of either TraceID randomness or explicit trace randomness,
495
+
which ensures that samplers always have sufficient randomness when using W3C Trace Context propagation.
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.
508
+
509
+
#### Random trace flag
510
+
511
+
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].
512
+
513
+
#### Explicit trace randomness
514
+
515
+
Explicit trace randomness is a mechanism that enables API users and
516
+
SDK authors to control trace randomness. The following recommendation
517
+
applies to Trace SDKs that have disregarded the recommendation on
518
+
TraceID randomness, above. It has two parts.
519
+
520
+
##### Do not overwrite explicit trace randomness
521
+
522
+
API users control the initial TraceState of a root span, so they can
523
+
provide explicit trace randomness for a trace by defining the [`rv`
524
+
sub-key of the OpenTelemetry TraceState][OTELRVALUE]. SDKs and Samplers
525
+
MUST NOT overwrite explicit trace randomness in an OpenTelemetry TraceState
526
+
value.
527
+
528
+
##### Root samplers set explicit trace randomness for non-random TraceIDs
529
+
530
+
When the SDK has generated a TraceID that does not meet the [W3C Trace
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].
551
+
552
+
#### IdGenerator randomness
553
+
554
+
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.
555
+
467
556
## Span Limits
468
557
469
558
Span attributes MUST adhere to the [common rules of attribute limits](../common/README.md#attribute-limits).
@@ -532,6 +621,18 @@ Additional `IdGenerator` implementing vendor-specific protocols such as AWS
532
621
X-Ray trace id generator MUST NOT be maintained or distributed as part of the
533
622
Core OpenTelemetry repositories.
534
623
624
+
### IdGenerator randomness
625
+
626
+
**Status**: [Development](../document-status.md)
627
+
628
+
Custom implementations of the `IdGenerator` SHOULD identify themselves
629
+
appropriately when all generated TraceID values meet the [W3C Trace
630
+
Context Level 2 randomness requirements][W3CCONTEXTTRACEID], so that
631
+
the Trace `random` flag will be set in the associated Trace contexts.
632
+
This is presumed to be a static property of the `IdGenerator`
633
+
implementation which can be inferred using language features, for
634
+
example by extending a marker interface.
635
+
535
636
## Span processor
536
637
537
638
Span processor is an interface which allows hooks for span start and end method
Copy file name to clipboardExpand all lines: specification/trace/tracestate-handling.md
+28Lines changed: 28 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -83,3 +83,31 @@ if ok {
83
83
// traceState was not updated.
84
84
}
85
85
```
86
+
87
+
## Pre-defined OpenTelemetry sub-keys
88
+
89
+
The following values have been defined by OpenTelemetry.
90
+
91
+
### Explicit randomness value `rv`
92
+
93
+
The OpenTelemetry TraceState `rv` sub-key defines an alternative source of randomness called the _explicit randomness value_.
94
+
Values of `rv` MUST be exactly 14 lower-case hexadecimal digits:
95
+
96
+
```
97
+
hexdigit = DIGIT ; a-f
98
+
```
99
+
100
+
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.
101
+
102
+
Lowercase hexadecimal digits are specified to enable direct lexicographical comparison between a sampling thresohld and either the TraceID (as it appears in the `traceparent` header) or the explicit randomness value (as it appears in the `tracestate` header).
103
+
104
+
Explicit randomness values are meant to propagate through [span contexts](../context/README.md) unmodified.
105
+
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.
106
+
107
+
For example, here is a W3C TraceState value including an OpenTelemetry explicit randomness value:
108
+
109
+
```
110
+
tracestate: ot=rv:6e6d1a75832a2f
111
+
```
112
+
113
+
This corresponds with the explicit randomness value, an unsigned integer value, of 0x6e6d1a75832a2f. This randomness value is meant to be used instead of the least-significant 56 bits of the TraceID. In this example, the 56-bit fraction (i.e., 0x6e6d1a75832a2f / 0x100000000000000 = 43.1%) supports making a consistent positive sampling decision at probabilities ranging from 56.9% through 100% (i.e., rejection thresohld values 0x6e6d1a75832a2f through 0), the same as for a hexadecimal TraceID ending in 6e6d1a75832a2f without explicit randomness value.
0 commit comments