Span Attribute Sampler

​

Considerations

​

Overview

The Span Attribute Sampler is an action designed to sample traces from a specified service based on conditions applied to span attributes. It supports several types of attribute evaluations:

• String Conditions: Check for existence, equality, inequality, substring containment, or regex matching.
• Number Conditions: Compare numeric attribute values using equality, inequality, or threshold comparisons.
• Boolean Conditions: Evaluate the presence of a boolean attribute or check for a specific boolean value.
• JSON Conditions: Validate JSON structure or evaluate nested JSON content using JSONPath expressions.

If any span from the specified service meets the condition, the trace is sampled. Otherwise, the trace is sampled based on the configured fallback sampling ratio.

​

Use Cases

​

Targeted Debugging

Sample only traces where a specific error flag is set. For example, sample traces from a checkout service where error = true.

See example →

​

Feature Rollout Monitoring

Retain traces for users or sessions flagged via JSON content. For instance, sample traces for an API service where the JSON payload indicates "user.role": "admin".

See example →

​

Route-Specific Analytics

Track performance or usage of specific endpoints by matching against HTTP target attributes.

See example →

​

Production Environment Sampling

Collect traces only from the production environment.

See example →

​

Latest Version Monitoring

Sample only traces from the latest relesed version, while still capturing a representative subset of older versions.

See example →

​

Configuration Options

​

Examples

Below are several YAML examples that demonstrate different use cases.

​

Match Error in Checkout Service

Sample traces where the error attribute (a boolean) equals true for the checkout-service.

apiVersion: actions.odigos.io/v1alpha1
kind: SpanAttributeSampler
metadata:
  name: checkout-errors
  namespace: odigos-system
spec:
  signals:
    - TRACES
  attribute_filters:
    - service_name: checkout-service
      attribute_key: error
      condition:
        boolean_condition:
          operation: equals
          expected_value: "true"
      fallback_sampling_ratio: 10

​

JSON Nested Attribute Match

For JSON evaluation, the JSON attribute is provided as a string. In this example the rule checks that the JSONPath expression returns a value and that the nested key equals the expected value.

apiVersion: actions.odigos.io/v1alpha1
kind: SpanAttributeSampler
metadata:
  name: admin-json-check
  namespace: odigos-system
spec:
  signals:
    - TRACES
  attribute_filters:
    - service_name: api-service
      attribute_key: payload
      condition:
        json_condition:
          operation: key_equals
          json_path: "$.user.role"
          expected_value: admin
      fallback_sampling_ratio: 5

​

Match HTTP Target Endpoint

Sample traces where the HTTP target endpoint (a string) contains /api/products.

apiVersion: actions.odigos.io/v1alpha1
kind: SpanAttributeSampler
metadata:
  name: match-api-products
  namespace: odigos-system
spec:
  signals:
    - TRACES
  attribute_filters:
    - service_name: frontend
      attribute_key: http.target
      condition:
        string_condition:
          operation: contains
          expected_value: "/api/products"
      fallback_sampling_ratio: 5

​

Sample Prod Traces

For example, sample all traces from the staging environment by matching on the env attribute.

apiVersion: actions.odigos.io/v1alpha1
kind: SpanAttributeSampler
metadata:
  name: sample-staging
  namespace: odigos-system
spec:
  signals:
    - TRACES
  attribute_filters:
    - service_name: orders-service
      attribute_key: env
      condition:
        string_condition:
          operation: equals
          expected_value: prod
      fallback_sampling_ratio: 1

​

Regex Condition (No Match)

The following example shows a regex condition for a version string. If the version does not match the expected pattern, the rule does not match the span. In this case, if the attribute exists but fails the regex test, the trace will not be sampled by this rule (and the fallback ratio applies).

apiVersion: actions.odigos.io/v1alpha1
kind: SpanAttributeSampler
metadata:
  name: version-regex-test
  namespace: odigos-system
spec:
  signals:
    - TRACES
  attribute_filters:
    - service_name: test-service
      attribute_key: version
      condition:
        string_condition:
          operation: regex
          expected_value: "^v1\.2\.\d+$"
      fallback_sampling_ratio: 12

​

Final Notes

• Multiple Filters: You can define multiple attribute filters across different services and attribute types. These filters are OR-combined; if any filter matches, the trace is sampled.
• Fallback Sampling: When no span satisfies the condition, the trace is sampled based on the fallback_sampling_ratio. This allows you to collect a percentage of non-matching traces for broad observability without overwhelming storage costs.
• JSON Evaluation: For JSON conditions, the sampler always uses the provided json_path to navigate the JSON structure. Ensure that the attribute value is a JSON-encoded string.

By following these guidelines and examples, you can configure the Span Attribute Sampler for production environments with clarity and precision.