-
Notifications
You must be signed in to change notification settings - Fork 888
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
OpenTelemetry TraceIdRatioBased sampler requirements following OTEP 235 #4166
base: main
Are you sure you want to change the base?
Changes from 14 commits
0524a3d
c5453f8
25a61fd
68fa270
51f9794
ba5a47b
49673b7
e51bea6
4afe1c7
2f0dc0b
f333b71
b7376bd
483b3fa
c40de50
15a9c6f
672fac2
3c80d97
b2b37f7
1bb0b31
2f0e387
6e29b0e
77b51f8
a61fbdd
59c329d
d21f341
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -30,7 +30,9 @@ linkTitle: SDK | |
+ [AlwaysOn](#alwayson) | ||
+ [AlwaysOff](#alwaysoff) | ||
+ [TraceIdRatioBased](#traceidratiobased) | ||
- [Requirements for `TraceIdRatioBased` sampler algorithm](#requirements-for-traceidratiobased-sampler-algorithm) | ||
- [`TraceIdRatioBased` sampler configuration](#traceidratiobased-sampler-configuration) | ||
- [`TraceIdRatioBased` sampler algorithm](#traceidratiobased-sampler-algorithm) | ||
- [`TraceIdRatioBased` sampler description](#traceidratiobased-sampler-description) | ||
+ [ParentBased](#parentbased) | ||
+ [JaegerRemoteSampler](#jaegerremotesampler) | ||
- [Span Limits](#span-limits) | ||
|
@@ -378,6 +380,7 @@ The default sampler is `ParentBased(root=AlwaysOn)`. | |
|
||
* Returns `RECORD_AND_SAMPLE` always. | ||
* Description MUST be `AlwaysOnSampler`. | ||
* OpenTelemetry TraceState SHOULD include `th:0`. | ||
|
||
#### AlwaysOff | ||
|
||
|
@@ -386,40 +389,41 @@ The default sampler is `ParentBased(root=AlwaysOn)`. | |
|
||
#### TraceIdRatioBased | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think there is a confusion that we need to help the users with. At first glance, This probably worth explicitly calling out. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
|
||
* The `TraceIdRatioBased` MUST ignore the parent `SampledFlag`. To respect the | ||
parent `SampledFlag`, the `TraceIdRatioBased` should be used as a delegate of | ||
the `ParentBased` sampler specified below. | ||
* Description MUST return a string of the form `"TraceIdRatioBased{RATIO}"` | ||
with `RATIO` replaced with the Sampler instance's trace sampling ratio | ||
represented as a decimal number. The precision of the number SHOULD follow | ||
implementation language standards and SHOULD be high enough to identify when | ||
Samplers have different ratios. For example, if a TraceIdRatioBased Sampler | ||
had a sampling ratio of 1 to every 10,000 spans it COULD return | ||
`"TraceIdRatioBased{0.000100}"` as its description. | ||
|
||
TODO: Add details about how the `TraceIdRatioBased` is implemented as a function | ||
of the `TraceID`. [#1413](https://github.com/open-telemetry/opentelemetry-specification/issues/1413) | ||
|
||
##### Requirements for `TraceIdRatioBased` sampler algorithm | ||
|
||
* The sampling algorithm MUST be deterministic. A trace identified by a given | ||
`TraceId` is sampled or not independent of language, time, etc. To achieve this, | ||
implementations MUST use a deterministic hash of the `TraceId` when computing | ||
the sampling decision. By ensuring this, running the sampler on any child `Span` | ||
will produce the same decision. | ||
* A `TraceIdRatioBased` sampler with a given sampling rate MUST also sample all | ||
traces that any `TraceIdRatioBased` sampler with a lower sampling rate would | ||
sample. This is important when a backend system may want to run with a higher | ||
sampling rate than the frontend system, this way all frontend traces will | ||
still be sampled and extra traces will be sampled on the backend only. | ||
* **WARNING:** Since the exact algorithm is not specified yet (see TODO above), | ||
there will probably be changes to it in any language SDK once it is, which | ||
would break code that relies on the algorithm results. | ||
Only the configuration and creation APIs can be considered stable. | ||
It is recommended to use this sampler algorithm only for root spans | ||
(in combination with [`ParentBased`](#parentbased)) because different language | ||
SDKs or even different versions of the same language SDKs may produce inconsistent | ||
results for the same input. | ||
The `TraceIdRatioBased` sampler implements simple, ratio-based probability sampling using randomness features specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. | ||
jmacd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
OpenTelemetry follows W3C Trace Context Level 2, which specifies 56 bits of randomness, in making use of 56 bits of information for probabilistic sampling decisions. | ||
jmacd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
[OpenTelemetry defines consistent probability sampling using 56 bits of randomness][CONSISTENTSAMPLING]. | ||
|
||
The `TraceIdRatioBased` sampler MUST ignore the parent `SampledFlag`. | ||
For respecting the parent `SampledFlag`, see the `ParentBased` sampler specified below. | ||
jmacd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
[W3CCONTEXTMAIN]: https://www.w3.org/TR/trace-context-2 | ||
|
||
##### `TraceIdRatioBased` sampler configuration | ||
|
||
The `TraceIdRatioBased` sampler is typically configured using a 32-bit or 64-bit floating point number to express the sampling ratio. | ||
The minimum valid sampling ratio is `2**-56`, and the maximum valid sampling ratio is 1.0. | ||
jmacd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
From an input sampling ratio, a rejection threshold value is calculated; see [consistent-probability sampler requirements][CONSISTENTSAMPLING] for details on converting sampling ratios into thresholds with variable precision. | ||
|
||
[CONSISTENTSAMPLING]: ./tracestate-probability-sampling.md | ||
|
||
##### `TraceIdRatioBased` sampler algorithm | ||
|
||
A Trace configured with sampling threshold `T`, a 56-bit unsigned number corresponding with the sampling ratio, has `ShouldSample()` called for a trace having randomness value `R`, a 56-bit unsigned random number. | ||
jmacd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
* If randomness value (R) is greater or equal to the rejection threshold (T), meaning when (R >= T), return `RECORD_AND_SAMPLE`, otherwise, return `DROP`. | ||
* When (R >= T), the OpenTelemetry TraceState SHOULD be modified to include the key-value `th:T` for rejection threshold value (T), as specified for the [OpenTelemetry TraceState `th` sub-key][TRACESTATEHANDLING]. | ||
|
||
[TRACESTATEHANDLING]: ./tracestate-handling.md#sampling-threshold-value-th | ||
|
||
##### `TraceIdRatioBased` sampler description | ||
|
||
The `TraceIdRatioBased` GetDescription MUST return a string of the form `"TraceIdRatioBased{RATIO}"` | ||
with `RATIO` replaced with the Sampler instance's trace sampling ratio | ||
represented as a decimal number. The precision of the number SHOULD follow | ||
implementation language standards and SHOULD be high enough to identify when | ||
Samplers have different ratios. For example, if a TraceIdRatioBased Sampler | ||
had a sampling ratio of 1 to every 10,000 spans it could return | ||
`"TraceIdRatioBased{0.000100}"` as its description. | ||
jmacd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
#### ParentBased | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same question as the other PR: if this is required, shouldn't there be a couple of implementations lined up before the spec change is merged?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have a shared my draft, open-telemetry/opentelemetry-go#5645, and @oertl has already merged an equivalent sampler in the Java contrib repository. (I would add that the OTel-Collector-Contrib probabilistic sampler processor acts as a near-prototype.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The connection with probabilistic sampler is detailed in #4243 and has been described as an interoperability specification.