docs(sdks): Propagated Sampling Rates & Strict Trace Propagation #11912
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
2 Skipped Deployments
|
antonpirker
reviewed
Nov 22, 2024
sentrivana
reviewed
Nov 22, 2024
|
|
||
| ### `tracesSampler` | ||
|
|
||
| This should be a callback, called when a transaction is started, which will be given a `samplingContext` object and which should return a sample rate between `0.0` and `1.0` _for the transaction in question_. This sample rate should behave the same way as the `tracesSampleRate` above, with the difference that it only applies to the newly-created transaction, such that different transactions can be sampled at different rates. Returning `0.0` should force the transaction to be dropped (set to `sampled = false`) and returning `1.0` should force the transaction to be sent (set `sampled = true`). | ||
|
|
||
| Optionally, the `tracesSampler` callback can also return a boolean to force a sampling decision (with `false` equivalent to `0.0` and `true` equivalent to `1.0`). If returning two different datatypes isn't an option in the implementing language, this possibility can safely be omitted. | ||
| Historically, the `tracesSampler` callback could have also returned a boolean to force a sampling decision (with `false` equivalent to `0.0` and `true` equivalent to `1.0`). This behavior is now **deprecated** and should be removed from all SDKs. |
There was a problem hiding this comment.
Why deprecate this and not just keep treating true as 1.0 and false as 0.0?
There was a problem hiding this comment.
What would be the benefit of doing so?
On first glance, I see a couple of downsides in having booleans in the API:
- It creates multiple overloads in the function signature or a polymorphic/mixed return type
- The semantics of
1.0(100%) for extrapolation are inherently clear, but forreturn Truenot so much. My expectation would be that we "inherit" the parent extrapolation factor, but in reality we apply a hidden 100% sample rate. - It's multiple ways to do the same thing.
cleptric
changed the title
Closed
Co-authored-by: Ivana Kellyer <ivana.kellyer@sentry.io> Co-authored-by: Anton Pirker <anton.pirker@sentry.io>
cleptric
commented
Nov 26, 2024
cleptric
commented
Nov 26, 2024
cleptric
commented
Nov 26, 2024
Co-authored-by: Anton Pirker <anton.pirker@sentry.io>
lizokm
approved these changes
Nov 26, 2024
jan-auer
approved these changes
Nov 26, 2024
Co-authored-by: Liza Mock <liza.mock@sentry.io>
Comment on lines
235
to
246
| 1. When an SDK starts a new trace, `sample_rand` is always set to a random number in range `[0, 1]`. This explicitly includes traces that are not sampled, as well as when the `tracesSampleRate` is set to `0.0` or `1.0`. | ||
| 2. It is _recommended_ to generate the random number deterministically using the trace ID as seed or source of randomness. The exact method by which the random number is created is implementation defined and may vary between SDK implementations. See 4. on why this behaviour is desirable. | ||
| 3. On incoming traces, an SDK assumes the `sample_rand` value along with the rest of the DSC, overriding an existing value if needed. | ||
| 4. If `sample_rand` is missing on an incoming trace, the SDK creates and from now on propagates a new random number on-the-fly, based on the following rules: | ||
| 1. If `sample_rate` and `sampled` are propgated, create `sample_rand` so that it adheres to the invariant. This means, for a decision of `True` generate a random number in half-open range `[0, rate)` and for a decision of `False` generate a random number in range `[rate, 1]`. | ||
| 2. If the `sampled` is missing `sample_rate`, generate a random number in the range `[0, 1]` like for a new trace. | ||
|
|
||
| The SDK should exclusively use the stored random number and no longer use `math.random()` or similar anywhere else in the tracing related code base: | ||
|
|
||
| 1. When the `tracesSampler` is invoked, this also applies to the return value of traces sampler. That is, `trace["sentry-sample_rand"] < tracesSampler(context)` | ||
| 2. Otherwise, when the SDK is the head of a trace, this also applies to sample decisions based on `tracesSampleRate`. That is, `trace["sentry-sample_rand"] < config.tracesSampleRate` | ||
| 3. There is no more direct comparison with `math.random()` during the sampling process. |
There was a problem hiding this comment.
I would really appreciate adding some examples, like we have above for strictTracePropagation, to see these rules in action. It would help me understand better how that actually works.
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.