Menu
Grafana Cloud

otelcol.processor.probabilistic_sampler

otelcol.processor.probabilistic_sampler accepts logs and traces data from other otelcol components and applies probabilistic sampling based on configuration options.

The probabilistic sampler processor supports several modes of sampling for spans and log records.
Sampling is performed on a per-request basis, considering individual items statelessly. For whole trace sampling, see otelcol.processor.tail_sampling.

For trace spans, this sampler supports probabilistic sampling based on a configured sampling percentage applied to the TraceID. In addition, the sampler recognizes a sampling.priority annotation, which can force the sampler to apply 0% or 100% sampling.

For log records, this sampler can be configured to use the embedded TraceID and follow the same logic as applied to spans.
When the TraceID is not defined, the sampler can be configured to apply hashing to a selected log record attribute.
This sampler also supports sampling priority.

Note

otelcol.processor.probabilistic_sampler is a wrapper over the upstream OpenTelemetry Collector Contrib probabilistic_sampler processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

You can specify multiple otelcol.processor.probabilistic_sampler components by giving them different labels.

Usage

alloy
otelcol.processor.probabilistic_sampler "LABEL" {
  output {
    logs    = [...]
    traces  = [...]
  }
}

Arguments

otelcol.processor.probabilistic_sampler supports the following arguments:

NameTypeDescriptionDefaultRequired
modestringSampling mode."proportional"no
hash_seeduint32An integer used to compute the hash algorithm.0no
sampling_percentagefloat32Percentage of traces or logs sampled.0no
sampling_precisionintThe number of hexadecimal digits used to encode the sampling threshold.4no
fail_closedboolWhether to reject items with sampling-related errors.trueno
attribute_sourcestringDefines where to look for the attribute in from_attribute."traceID"no
from_attributestringThe name of a log record attribute used for sampling purposes.""no
sampling_prioritystringThe name of a log record attribute used to set a different sampling priority from the sampling_percentage setting.""no

You can set mode to "proportional", "equalizing", or "hash_seed". The default is "proportional" unless either hash_seed is configured or attribute_source is set to record. For more information on modes, refer to the upstream Collector’s Mode Selection documentation section.

hash_seed determines an integer to compute the hash algorithm. This argument could be used for both traces and logs. When used for logs, it computes the hash of a log record. For hashing to work, all collectors for a given tier, for example, behind the same load balancer, must have the same hash_seed. It is also possible to leverage a different hash_seed at different collector tiers to support additional sampling requirements.

sampling_percentage determines the percentage at which traces or logs are sampled. All traces or logs are sampled if you set this argument to a value greater than or equal to 100.

attribute_source (logs only) determines where to look for the attribute in from_attribute. The allowed values are traceID or record.

from_attribute (logs only) determines the name of a log record attribute used for sampling purposes, such as a unique log record ID. The value of the attribute is only used if the trace ID is absent or if attribute_source is set to record.

sampling_priority (logs only) determines the name of a log record attribute used to set a different sampling priority from the sampling_percentage setting. 0 means to never sample the log record, and greater than or equal to 100 means to always sample the log record.

The probabilistic_sampler supports two types of sampling for traces:

  1. sampling.priority semantic convention as defined by OpenTracing.
  2. Trace ID hashing.

The sampling.priority semantic convention takes priority over trace ID hashing. Trace ID hashing samples based on hash values determined by trace IDs.

The probabilistic_sampler supports sampling logs according to their trace ID, or by a specific log record attribute.

sampling_precision must be a value between 1 and 14 (inclusive).

Blocks

The following blocks are supported inside the definition of otelcol.processor.probabilistic_sampler:

HierarchyBlockDescriptionRequired
debug_metricsdebug_metricsConfigures the metrics that this component generates to monitor its state.no

debug_metrics block

The debug_metrics block configures the metrics that this component generates to monitor its state.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
disable_high_cardinality_metricsbooleanWhether to disable certain high cardinality metrics.trueno
levelstringControls the level of detail for metrics emitted by the wrapped collector."detailed"no

disable_high_cardinality_metrics is the Grafana Alloy equivalent to the telemetry.disableHighCardinalityMetrics feature gate in the OpenTelemetry Collector. It removes attributes that could cause high cardinality metrics. For example, attributes with IP addresses and port numbers in metrics about HTTP and gRPC connections are removed.

Note

If configured, disable_high_cardinality_metrics only applies to otelcol.exporter.* and otelcol.receiver.* components.

level is the Alloy equivalent to the telemetry.metrics.level feature gate in the OpenTelemetry Collector. Possible values are "none", "basic", "normal" and "detailed".

Exported fields

The following fields are exported and can be referenced by other components:

NameTypeDescription
inputotelcol.ConsumerA value that other components can use to send telemetry data to.

input accepts otelcol.Consumer OTLP-formatted data for any telemetry signal of these types:

  • logs
  • traces

Component health

otelcol.processor.probabilistic_sampler is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.processor.probabilistic_sampler does not expose any component-specific debug information.

Examples

Basic usage

alloy
otelcol.processor.probabilistic_sampler "default" {
  hash_seed           = 123
  sampling_percentage = 15.3

  output {
    logs = [otelcol.exporter.otlp.default.input]
  }
}

Sample 15% of the logs

alloy
otelcol.processor.probabilistic_sampler "default" {
  sampling_percentage = 15

  output {
    logs = [otelcol.exporter.otlp.default.input]
  }
}

Sample logs according to their “logID” attribute

alloy
otelcol.processor.probabilistic_sampler "default" {
  sampling_percentage = 15
  attribute_source    = "record"
  from_attribute      = "logID"

  output {
    logs = [otelcol.exporter.otlp.default.input]
  }
}

Sample logs according to a “priority” attribute

alloy
otelcol.processor.probabilistic_sampler "default" {
  sampling_percentage = 15
  sampling_priority   = "priority"

  output {
    logs = [otelcol.exporter.otlp.default.input]
  }
}

Compatible components

otelcol.processor.probabilistic_sampler can accept arguments from the following components:

otelcol.processor.probabilistic_sampler has exports that can be consumed by the following components:

Note

Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.