Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.odigos.io/llms.txt

Use this file to discover all available pages before exploring further.

This page describes how sampling rules are evaluated in Odigos: the three rule categories (Noisy Operation, Highly Relevant, Cost Reduction), the order between categories, and how conflicts inside a category resolve. Each category has its own page; this overview focuses on how the categories interact.

​
Rule categories

Noisy Operation

Traffic with little or no value (for example Kubernetes health probes). Decided early at the root span with head sampling.

Highly Relevant

Important traffic aligned with RED-style signals (errors, duration). Each rule’s Keep Percentage controls how much is retained.

Cost Reduction

Caps applied to remaining traffic to control volume and cost (for example a percentage across the cluster or a specific route).
See Head vs. tail sampling for how head and tail sampling differ in Odigos (root-span decisions versus aggregation at the gateway).
If you only define Highly Relevant rules and no Cost Reduction rules, unimportant traffic is not aggressively reduced by those rules alone—policy may still require full-trace context to evaluate importance, which increases gateway work without cutting volume. Use Highly Relevant and Cost Reduction together when you need both signal and volume control.

​
Order of operations between categories

Categories are not all evaluated for every trace in parallel. Odigos applies them in this fixed sequence:

Noisy Operation

If the trace matches a Noisy rule, it is dropped or sampled down as configured. The trace exits the pipeline at this stage; Highly Relevant and Cost Reduction are not evaluated for that trace.

Highly Relevant

Only traces that did not match any Noisy rule reach this stage. Rules here classify important traffic (for example errors and duration); important matches can still be sampled per each rule’s Keep Percentage. Traces continue to Cost Reduction after this stage.

Cost Reduction

For traces that match rules in this category after the earlier stages, this stage applies caps to control volume and cost.
The pipeline runs the categories in this order. At each stage, every rule in that category is considered; how multiple matches resolve is covered in Rule evaluation.

​
Rule evaluation

​
Evaluation inside a category

Within a single category, rule order does not matter. When multiple rules match the same trace, the engine combines them so all of them are satisfied at once. For Highly Relevant, percentages are floors — the highest keep percentage wins, so any retention guarantee is honored. For Noisy Operation and Cost Reduction, percentages are caps — the lowest keep percentage wins, so the strictest cap is honored. This makes it safe to add rules without fear of one silently overriding another.

​
Evaluation between Highly Relevant and Cost Reduction categories

When a trace matches rules in both the Highly Relevant and Cost Reduction categories, the Highly Relevant keep percentage always wins — regardless of whether it is higher or lower than the Cost Reduction cap.

Highly Relevant rate higher than Cost Reduction

Trace: POST /api/orders that returned a 500 error.Matching rules:
  • Highly Relevant — keep 100% of error traces.
  • Cost Reduction — keep at most 10% of /api/orders traffic.
Outcome: the trace is kept at 100%. Highly Relevant overrides the Cost Reduction cap.

Highly Relevant rate lower than Cost Reduction

Trace: GET /api/products that took 750 ms.Matching rules:
  • Highly Relevant — keep 25% of traces longer than 500 ms.
  • Cost Reduction — keep at most 50% of /api/products traffic.
Outcome: the trace is kept at 25%. Highly Relevant still wins, even though its keep rate is lower than the Cost Reduction cap.

​
Why full traces still matter

For traces that are evaluated on the tail path, the evaluator needs the assembled trace (within the aggregation window) so it can apply Highly Relevant conditions that depend on any span. That is why tail sampling and aggregation are part of the pipeline for those policies, even when the category order is Noisy → Highly Relevant → Cost Reduction.