Examples

End-to-end walkthroughs of common sampling rules. Each example shows the rule in the UI and as a YAML Sampling resource (the same CRD applied via kubectl apply or GitOps). Use these as starting points and adjust scope, operations, and percentages to match your environment.

YAML examples are accurate against the current Sampling CRD schema. The screenshots for each scenario reflect the live UI; minor styling may shift between releases.

For the field reference behind each example—every Source scope option, every Operation option, every Keep Percentage choice—see Configuration. For the rules engine itself, see Rules.

YAML examples on this page conform to the Sampling CRD (odigos.io/v1alpha1). For every field, type, validation rule, and default—including options not covered by the examples below—see the Sampling API reference.

Scope rules to only the workloads they need to evaluate. Cluster-wide rules are checked against every trace; tightly scoped rules (Specific Source, Namespace, or Language) are skipped entirely for unrelated workloads, which avoids wasted matching work in the gateway. Several examples below illustrate this pattern.

1. Drop a noisy custom endpoint

Goal: Drop traces for a high-volume polling endpoint (/api/v1/poll) that produces many traces but is not useful for debugging or SLOs. This is a typical Noisy rule for traffic that’s neither a Kubernetes probe nor a metrics scrape, but is still pure noise.

UI
YAML

Create a Noisy rule with:

Name: Drop polling endpoint
Notes: High-volume poll endpoint with no SLO/debug value.
Source scope: Specific Source = odimall / Deployment / notification-service
Operation: HTTP Server, route prefix /api/v1/poll, method GET
Drop Percentage: Drop All

UI screenshot of a Noisy rule that drops GET traces for /api/v1/poll, scoped to the notification-service Deployment in the odimall namespace.

drop-poll-endpoint.yaml

apiVersion: odigos.io/v1alpha1
kind: Sampling
metadata:
  name: drop-poll-endpoint
  namespace: odigos-system
spec:
  name: Drop /api/v1/poll
  noisyOperations:
    - name: Drop polling endpoint
      notes: High-volume poll endpoint with no SLO/debug value.
      percentageAtMost: 0
      sourceScopes:
        - workloadNamespace: odimall
          workloadKind: Deployment
          workloadName: notification-service
      operation:
        httpServer:
          routePrefix: /api/v1/poll
          method: GET

2. Keep slow requests at 100%

Goal: Always retain traces for GET /api/products whenever they take longer than 500 ms. This is a Highly Relevant duration rule—a complement to the built-in Keep All Error Traces rule, focused on latency rather than errors.

UI
YAML

Create a Highly Relevant rule with:

Name: Slow GET /api/products
Notes: SLO-relevant path; retain anything over 500ms for investigation.
Rule Type: Duration
Source scope: Specific Source = odimall / Deployment / frontend
Operation: HTTP Server, route /api/products, method GET
Keep Percentage: Keep All
Duration: 500ms

UI screenshot of a Highly Relevant rule that keeps 100% of slow GET /api/products traces, scoped to the frontend Deployment in the odimall namespace.

keep-slow-products.yaml

apiVersion: odigos.io/v1alpha1
kind: Sampling
metadata:
  name: keep-slow-products
  namespace: odigos-system
spec:
  name: Keep slow product reads
  highlyRelevantOperations:
    - name: Slow GET /api/products
      notes: SLO-relevant path; retain anything over 500ms for investigation.
      durationAtLeastMs: 500
      percentageAtLeast: 100
      sourceScopes:
        - workloadNamespace: odimall
          workloadKind: Deployment
          workloadName: frontend
      operation:
        httpServer:
          route: /api/products
          method: GET

3. Apply a cluster-wide 5% baseline

Goal: Keep 5% of all cluster traffic as a statistical baseline, regardless of source or operation. This is the same shape as the built-in Drop Traces Cluster-Wide rule and is the simplest way to cut volume after Noisy and Highly Relevant rules have run.

UI
YAML

Create a Cost Reduction rule with:

Name: 5% baseline
Notes: Statistical baseline for non-noisy, non-important traffic.
Source scope: Entire cluster
Operation: All Operations
Drop Percentage: 5

UI screenshot of a Cost Reduction rule that caps cluster-wide retention at 5%.

baseline-cluster-sample.yaml

apiVersion: odigos.io/v1alpha1
kind: Sampling
metadata:
  name: baseline-cluster-sample
  namespace: odigos-system
spec:
  name: Cluster baseline 5%
  costReductionRules:
    - name: 5% baseline
      notes: Statistical baseline for non-noisy, non-important traffic.
      percentageAtMost: 5

Cost Reduction rules with no Operation block apply to every operation in the scope. Combine with Highly Relevant rules to make sure error and latency traces survive the cap—Highly Relevant always wins over Cost Reduction.

4. Scope a rule to namespace and language

Goal: Drop scrape traffic to /internal/metrics for Java workloads in the prod namespace only—leave other namespaces and other languages untouched. This example demonstrates the AND semantics across scope types: a single source scope item with both workloadNamespace and workloadLanguage set.

UI
YAML

Create a Noisy rule with:

Name: Java metrics scrape in prod
Notes: Internal Prometheus scrape endpoint; the scrape itself isn't useful for tracing.
Source scope: Specific Namespace = prod and Specific Programming Language = Java
Operation: HTTP Server, route /internal/metrics, method GET
Drop Percentage: Drop All

UI screenshot of a Noisy rule scoped with namespace prod AND language Java.

drop-metrics-java-prod.yaml

apiVersion: odigos.io/v1alpha1
kind: Sampling
metadata:
  name: drop-metrics-java-prod
  namespace: odigos-system
spec:
  name: Drop /internal/metrics (Java in prod)
  noisyOperations:
    - name: Java metrics scrape in prod
      notes: Internal Prometheus scrape endpoint; the scrape itself isn't useful for tracing.
      percentageAtMost: 0
      sourceScopes:
        - workloadNamespace: prod
          workloadLanguage: java
      operation:
        httpServer:
          route: /internal/metrics
          method: GET

Source scope combines in two layers:

Different categories must all match. This rule sets Specific Namespace = prod together with Specific Programming Language = java, so a workload has to be in prod and be a Java workload. In YAML that maps to a single sourceScopes item with both fields set on it.
Multiple values inside one category are alternatives. Setting the namespace category to prod and staging would match a Java workload in either one. In YAML that maps to multiple sourceScopes items, each carrying just the namespace field.

5. Combine Highly Relevant and Cost Reduction

Goal: A payment-service where every error trace must be kept (Highly Relevant) and all other traffic is capped at 1% (Cost Reduction). This is the canonical “keep what matters, sample the rest” pattern, expressed in a single Sampling object that bundles both categories together.

UI
YAML

Create two rules:1. Highly Relevant

Name: Keep payment-service errors
Notes: Errors from payment-service are always investigated; never sample them away.
Rule Type: Error
Source scope: Specific Source = odimall / Deployment / payment-service
Operation: All Operations
Keep Percentage: Keep All

UI screenshot of a Highly Relevant rule with Rule Type Error scoped to payment-service, Keep at least 100%.

2. Cost Reduction

Name: payment-service 1% cap
Notes: Cap healthy payment-service traffic to keep cost in check; HR errors above always win.
Source scope: Specific Source = odimall / Deployment / payment-service
Operation: All Operations
Drop Percentage: 1%

UI screenshot of a Cost Reduction rule on payment-service with Keep at most 1%.

payment-service-policy.yaml

apiVersion: odigos.io/v1alpha1
kind: Sampling
metadata:
  name: payment-service-policy
  namespace: odigos-system
spec:
  name: payment-service policy
  notes: Always keep errors; cap healthy traffic at 1%.
  highlyRelevantOperations:
    - name: Keep payment-service errors
      notes: Errors from payment-service are always investigated; never sample them away.
      error: true
      percentageAtLeast: 100
      sourceScopes:
        - workloadNamespace: odimall
          workloadKind: Deployment
          workloadName: payment-service
  costReductionRules:
    - name: payment-service 1% cap
      notes: Cap healthy payment-service traffic to keep cost in check; HR errors above always win.
      percentageAtMost: 1
      sourceScopes:
        - workloadNamespace: odimall
          workloadKind: Deployment
          workloadName: payment-service

A trace from payment-service that contains any error span is kept at 100% by the Highly Relevant rule. A trace with no errors falls through to the Cost Reduction cap of 1%. Both rules are evaluated for every matching trace; Highly Relevant’s keep percentage wins when both apply. See Evaluation between Highly Relevant and Cost Reduction.

YAML reference notes

A few details that aren’t obvious from YAML alone but matter when authoring rules. The full schema—every field, type, and validation rule—is in the Sampling API reference.

Source scope: language enum and workloadKind casing

The YAML enum for workloadLanguage uses lowercase identifiers: java, python, go, dotnet, javascript, php, ruby. The UI displays the friendly names (Java, Python, Go, .Net, NodeJS, PHP, Ruby).workloadKind must match the Kubernetes resource kind exactly (case-sensitive PascalCase): Deployment, StatefulSet, DaemonSet, Job, CronJob. Lowercase or pluralized values will silently fail to match.

Defaults when fields are omitted

Empty or missing fields don’t mean “match nothing”—each one has a default that often biases toward broader matching:

sourceScopes empty or absent — the rule matches every source.
operation omitted — the rule matches every operation in the scope.
Noisy percentageAtMost omitted — defaults to 0% (drops everything).
Highly Relevant percentageAtLeast omitted — defaults to 100% (keeps everything).
Cost Reduction percentageAtMost — required. There is no default; the resource will fail validation if the field is absent.

HTTP matchers: route, method, and templated paths

On HTTP Server matchers, set either route (exact match) or routePrefix (prefix match)—not both. Both match the framework’s templated path (e.g., /users/{id}, /users/:id, /users/*), not the resolved URL.
method is a free-form string in YAML. The UI restricts it to GET, POST, PATCH, DELETE, and PUT, but YAML accepts any method (e.g., HEAD, OPTIONS). Leave it empty to match any method.
HTTP Client matchers (Noisy only) use templatedPath / templatedPathPrefix—the framework’s parameterized path (e.g., /users/{id}), not the resolved URL (e.g., /users/42). Match against the route as your HTTP library reports it.

Kafka matchers: empty topic matches all topics

Leaving kafkaTopic empty on a kafkaConsumer or kafkaProducer matcher matches every topic for that direction. Set the topic explicitly to scope a Kafka rule to a specific stream.

Highly Relevant: combining `error` and `durationAtLeastMs`

Setting both error: true and durationAtLeastMs on a single highlyRelevantOperations item is an AND—the span must be an error and longer than the threshold to match. For “errors or slow,” use two separate items in the highlyRelevantOperations array.

`name` and `disabled` surface in observability data

The rule name is written as a metric attribute and stored as a span attribute on participating spans, so use a value that’s safe for dashboards and queries—avoid PII or characters your backend doesn’t index well.disabled: true (per rule, or spec.disabled for the entire Sampling object) removes the rule from sampling decisions but still emits metrics for it. That’s useful for tuning a rule and observing its would-be impact before re-enabling it, rather than deleting it outright.

Applying YAML rules

You can apply any of the YAML examples above with kubectl, or commit them to your GitOps repository alongside the rest of your Odigos configuration:

kubectl apply -f drop-poll-endpoint.yaml

Each Sampling resource is a self-contained group of rules. You can split rules across multiple Sampling objects—by team, environment, or use case—and they will be joined together to form the global sampling policy.

kubectl get samplings.odigos.io -n odigos-system

Disabling a rule

To take a rule out of sampling decisions without deleting it, you can either flip the toggle in the UI or set disabled: true in YAML. Disabled rules still emit sampling metrics, so you can observe what the rule would have done before re-enabling it—useful as a “soft delete” while tuning, rather than removing the rule outright. See Enabled for when to reach for this versus deleting the rule.

UI
YAML

Each rule’s detail view has a toggle in the top-right corner that flips its label between Rule Enabled and Rule Disabled. Slide it off to take the rule out of sampling decisions immediately; slide it back on to re-enable. The toggle is per rule—other rules in the same Sampling object continue to apply.

UI screenshot of the Rule Enabled toggle in the on (green) position.

UI screenshot of the Rule Disabled toggle in the off (red) position.

The disabled flag exists at two levels:

Per rule — set disabled: true on an individual entry in noisyOperations, highlyRelevantOperations, or costReductionRules. The other rules in the same Sampling object continue to apply. This is what the UI toggle writes.
Per Sampling object — set spec.disabled: true on the resource. Every rule in that object is taken out of decisions in one step, leaving rules in other Sampling objects untouched.

disable-a-rule.yaml

apiVersion: odigos.io/v1alpha1
kind: Sampling
metadata:
  name: payment-service-policy
  namespace: odigos-system
spec:
  name: payment-service policy
  costReductionRules:
    - name: payment-service 1% cap
      notes: Cap healthy payment-service traffic to keep cost in check; HR errors above always win.
      disabled: true
      percentageAtMost: 1
      sourceScopes:
        - workloadNamespace: odimall
          workloadKind: Deployment
          workloadName: payment-service

The examples on this page cover the most common shapes; the Sampling API reference is the source of truth for every field, type, validation rule, and default on the CRD. Use it when you’re extending an example or building a rule that doesn’t fit one of the patterns above.

Getting Started

Instrumentations

Odigos Pipeline

Destinations

Concepts

Contribution Guidelines

1. Drop a noisy custom endpoint

2. Keep slow requests at 100%

3. Apply a cluster-wide 5% baseline

4. Scope a rule to namespace and language

5. Combine Highly Relevant and Cost Reduction

YAML reference notes

Applying YAML rules

Disabling a rule

Getting Started

Instrumentations

Odigos Pipeline

Destinations

Concepts

Contribution Guidelines

Documentation Index

​1. Drop a noisy custom endpoint

​2. Keep slow requests at 100%

​3. Apply a cluster-wide 5% baseline

​4. Scope a rule to namespace and language

​5. Combine Highly Relevant and Cost Reduction

​YAML reference notes

​Applying YAML rules

​Disabling a rule

1. Drop a noisy custom endpoint

2. Keep slow requests at 100%

3. Apply a cluster-wide 5% baseline

4. Scope a rule to namespace and language

5. Combine Highly Relevant and Cost Reduction

YAML reference notes

Applying YAML rules

Disabling a rule