Skip to content

Commit 396ba0f

Browse files
authored
add TBS examples to explain policy naunces (#1239)
1 parent ea451a6 commit 396ba0f

File tree

1 file changed

+45
-1
lines changed

1 file changed

+45
-1
lines changed

solutions/observability/apm/transaction-sampling.md

+45-1
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ Trace events are matched to policies in the order specified. Each policy list mu
272272
Note that from version `9.0.0` APM Server has an unlimited storage limit, but will stop writing when the disk where the database resides reaches 80% usage. Due to how the limit is calculated and enforced, the actual disk space may still grow slightly over this disk usage based limit, or any configured storage limit.
273273
::::
274274

275-
### Example configuration [_example_configuration]
275+
### Example configuration 1 [_example_configuration_1]
276276

277277
This example defines three tail-based sampling polices:
278278

@@ -290,6 +290,50 @@ This example defines three tail-based sampling polices:
290290
2. Samples 1% of traces in `production` with the trace name `"GET /not_important_route"`
291291
3. Default policy to sample all remaining traces at 10%, e.g. traces in a different environment, like `dev`, or traces with any other name
292292

293+
### Example configuration 2 [_example_configuration_2]
294+
295+
When a trace originates in Service A and then calls Service B, the sampling rate is determined by the service where the trace starts:
296+
297+
```yaml
298+
- sample_rate: 0.3
299+
service.name: B
300+
- sample_rate: 0.5
301+
service.name: A
302+
- sample_rate: 0.1 # Fallback: always set a default
303+
```
304+
305+
- Because Service A is the root of the trace, its policy (0.5) is applied while Service B's policy (0.3) is ignored.
306+
- If instead the trace began in Service B (and then passed to Service A), the policy for Service B would apply.
307+
308+
:::{note}
309+
Tail‑based sampling rules are evaluated at the *trace level* based on which service initiated the distributed trace, not the service of the transaction or span.
310+
:::
311+
312+
### Example configuration 3 [_example_configuration_3]
313+
314+
Policies are evaluated **in order** and the first one that meets all match conditions is applied. That means, in practice, order policies from most specific (narrow matchers) to most general, ending with a catch-all (fallback).
315+
316+
```yaml
317+
# Example A: prioritize service origin, then failures
318+
- sample_rate: 0.2
319+
service.name: A
320+
- sample_rate: 0.5
321+
trace.outcome: failure
322+
- sample_rate: 0.1 # catch-all
323+
```
324+
325+
```yaml
326+
# Example B: prioritize failures, then a specific service
327+
- sample_rate: 0.2
328+
trace.outcome: failure
329+
- sample_rate: 0.5
330+
service.name: A
331+
- sample_rate: 0.1
332+
```
333+
334+
- In Example A, traces from Service A are sampled at 20%, and all other failed traces (regardless of service) are sampled at 50%.
335+
- In Example B, every failed trace is sampled at 20%, including those originating from Service A.
336+
293337
### Configuration reference [_configuration_reference]
294338

295339
#### Top-level tail-based sampling settings [_top_level_tail_based_sampling_settings]

0 commit comments

Comments
 (0)