This action is a Service Action that samples traces based on the presence or value of specific attributes within a trace.
This feature is in beta. It may be subject to changes and improvements based on user feedback.
Before enabling the Service Name Sampler, please consider the following:
json_condition
will cause a higher resource utilization!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:
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.
Using JSON Conditions will cause spikes in performance and resources utilization.
Sample only traces where a specific error flag is set. For example, sample traces from a checkout service where error = true
.
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"
.
Track performance or usage of specific endpoints by matching against HTTP target attributes.
Collect traces only from the production environment.
Sample only traces from the latest relesed version, while still capturing a representative subset of older versions.
actionName
actionName string
: Allows you to attach a meaningful name to the action for convenience.
notes
notes string
: Allows you to attach notes regarding the action for convenience.
disabled
disabled boolean
: Allows you to temporarily disable the action, but keep it saved for future use.
false
signals *
signals string[]
: An array with the signals that the processor will act on.
TRACES
attribute_filters *
attribute_filters object[]
: An array of objects representing the filters for the service and attribute filters.
service_name *
service_name string
: Specifies the service name to search within the trace (Across all available spans).
attribute_key *
attribute_key string
: Specifies the attribute key inside of the span.
condition *
condition object
: An object representing the filters for span attributes filters.
string_condition
operation
operation string
: Specifies the operation to run against the attribute.
accepted values for the boolean operation:
expected_value
expected_value string
: The values to test the attribute against.
[equals, not_equals, contains, not_contains, regex]
.number_condition
operation
operation string
: Specifies the operation to run against the attribute.
accepted values for the number condition:
expected_value
expected_value float
: The values to test the attribute against.
[equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal]
.boolean_condition
operation
operation string
: Specifies the operation to run against the attribute.
accepted values for the boolean operation:
expected_value
expected_value boolean
: The values to test the attribute against.
equals
.json_condition
operation
operation string
: Specifies the operation to run against the attribute.
accepted values for the boolean operation:
expected_value
expected_value string
: The values to test the attribute against.
[equals, not_equals, jsonpath_exists, key_equals, key_not_equals]
.json_path
json_path string
: It is a JSONPath expression used to navigate the JSON structure.
[jsonpath_exists, key_equals, key_not_equals]
.fallback_sampling_ratio *
fallback_sampling_ratio float
: Specifies the percentage of traces that don’t meet the service name filter and that you still like to retain.
If any span from the specified service satisfies the attribute condition, the trace is sampled. If no match is found, the trace is sampled based on the fallback ratio.
Below are several YAML examples that demonstrate different use cases.
Sample traces where the error
attribute (a boolean) equals true
for the checkout-service
.
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.
Sample traces where the HTTP target endpoint (a string) contains /api/products.
For example, sample all traces from the staging environment by matching on the env attribute.
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).
fallback_sampling_ratio
. This allows you to collect a percentage of non-matching traces for broad observability without overwhelming storage costs.By following these guidelines and examples, you can configure the Span Attribute Sampler for production environments with clarity and precision.