Documentation Grafana Alloy Reference Components otelcol otelcol.processor.filter

otelcol.processor.filter

otelcol.processor.filter filters out accepted telemetry data from other otelcol components using the OpenTelemetry Transformation Language (OTTL). If any of the OTTL statements evaluates to true, the telemetry data is dropped.

OTTL statements consist of OTTL Converter functions, which act on paths. A path is a reference to a telemetry data such as:

• Resource attributes.
• Instrumentation scope name.
• Span attributes.

In addition to the standard OTTL Converter functions, the following metrics-only functions are used exclusively by the processor:

• HasAttrKeyOnDataPoint
• HasAttrOnDataPoint

OTTL statements used in otelcol.processor.filter mostly contain constructs such as:

• Booleans:
  • not true
  • not IsMatch(name, "http_.*")
• Math expressions:
  • 1 + 1
  • end_time_unix_nano - start_time_unix_nano
  • sum([1, 2, 3, 4]) + (10 / 1) - 1

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

Usage

alloy Copy

otelcol.processor.filter "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following argument with otelcol.processor.filter:

The supported values for error_mode are:

• ignore: Ignore errors returned by conditions, log them, and continue on to the next condition. This is the recommended mode.
• silent: Ignore errors returned by conditions, don’t log them, and continue on to the next condition.
• propagate: Return the error up the pipeline. This will result in the payload being dropped from Alloy.

Blocks

You can use the following blocks with otelcol.processor.filter:

output

Required

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

You must specify the output block, but all its arguments are optional. By default, telemetry data is dropped. Configure the metrics, logs, and traces arguments accordingly to send telemetry data to other components.

debug_metrics

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

The following arguments are supported:

disable_high_cardinality_metrics is the 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.

logs

The logs block specifies statements that filter log telemetry signals. Only logs blocks can be specified.

The syntax of OTTL statements depends on the OTTL context. Refer to the OpenTelemetry documentation for more information:

• OTTL log context

Only one of the statements inside the list of statements has to be satisfied.

metrics

The metrics block specifies statements that filter metric telemetry signals. Only one metrics blocks can be specified.

The syntax of OTTL statements depends on the OTTL context. Refer to the OpenTelemetry documentation for more information:

• OTTL metric context
• OTTL datapoint context

Statements are checked in order from “high level” to “low level” telemetry, in this order:

1. metric
2. datapoint

If at least one metric condition is satisfied, the datapoint conditions won’t be checked. Only one of the statements inside the list of statements has to be satisfied.

If all datapoints for a metric are dropped, the metric will also be dropped.

traces

The traces block specifies statements that filter trace telemetry signals. Only one traces block can be specified.

The syntax of OTTL statements depends on the OTTL context. See the OpenTelemetry documentation for more information:

• OTTL span context
• OTTL spanevent context

Statements are checked in order from “high level” to “low level” telemetry, in this order:

1. span
2. spanevent

If at least one span condition is satisfied, the spanevent conditions won’t be checked. Only one of the statements inside the list of statements has to be satisfied.

If all span events for a span are dropped, the span will be left intact.

Exported fields

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

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

otelcol.processor.filter doesn’t expose any component-specific debug information.

Debug metrics

otelcol.processor.filter doesn’t expose any component-specific debug metrics.

Examples

Drop spans which contain a certain span attribute

This example drops the signals that have the attribute container.name set to the value app_container_1.

alloy Copy

otelcol.processor.filter "default" {
  error_mode = "ignore"

  traces {
    span = [
      `attributes["container.name"] == "app_container_1"`,
    ]
  }

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

Drop metrics based on either of two criteria

This example drops metrics which satisfy at least one of two OTTL statements:

• The metric name is my.metric and there is a my_label resource attribute with a value of abc123.
• The metric is a histogram.

alloy Copy

otelcol.processor.filter "default" {
  error_mode = "ignore"

  metrics {
    metric = [
       `name == "my.metric" and resource.attributes["my_label"] == "abc123"`,
       `type == METRIC_DATA_TYPE_HISTOGRAM`,
    ]
  }

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

Drop non-HTTP spans and sensitive logs

alloy Copy

otelcol.processor.filter "default" {
  error_mode = "ignore"

  traces {
    span = [
      `attributes["http.request.method"] == nil`,
    ]
  }

  logs {
    log_record = [
      `IsMatch(body, ".*password.*")`,
      `severity_number < SEVERITY_NUMBER_WARN`,
    ]
  }

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

Compatible components

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

• Components that export OpenTelemetry otelcol.Consumer

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

• Components that consume OpenTelemetry otelcol.Consumer