---
title: "otelcol.processor.filter | Grafana Alloy documentation"
description: "Learn about otelcol.processor.filter"
---

# `otelcol.processor.filter`

`otelcol.processor.filter` filters out accepted telemetry data from other `otelcol` components using the [OpenTelemetry Transformation Language (OTTL)](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/README.md). If any of the OTTL statements evaluates to **true**, the telemetry data is **dropped**.

OTTL statements consist of [OTTL Converter functions](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/pkg/ottl/ottlfuncs#converters), 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/pkg/ottl/ottlfuncs#converters), the following metrics-only functions are used exclusively by the processor:

- [HasAttrKeyOnDataPoint](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/processor/filterprocessor/README.md#hasattrkeyondatapoint)
- [HasAttrOnDataPoint](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/processor/filterprocessor/README.md#hasattrondatapoint)

[OTTL](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/README.md) statements used in `otelcol.processor.filter` mostly contain constructs such as:

- [Booleans](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/pkg/ottl#booleans):
  
  - `not true`
  - `not IsMatch(name, "http_.*")`
- [Math expressions](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/pkg/ottl#math-expressions):
  
  - `1 + 1`
  - `end_time_unix_nano - start_time_unix_nano`
  - `sum([1, 2, 3, 4]) + (10 / 1) - 1`

> Note
> 
> Raw Alloy syntax strings can be used to write OTTL statements. For example, the OTTL statement `attributes["grpc"] == true` is written in Alloy syntax as \`attributes\[“grpc”] == true\`

> Note
> 
> `otelcol.processor.filter` is a wrapper over the upstream OpenTelemetry Collector [`filter`](https://github.com/open-telemetry/opentelemetry-collector/tree/v0.147.0/filter) processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

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

> Warning
> 
> Exercise caution when using `otelcol.processor.filter`:
> 
> - Make sure you understand schema/format of the incoming data and test the configuration thoroughly. In general, use a configuration that’s as specific as possible ensure you retain only the data you want to keep.
> - [Orphaned Telemetry](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.85.0/docs/standard-warnings.md#orphaned-telemetry): The processor allows dropping spans. Dropping a span may lead to orphaned spans if the dropped span is a parent. Dropping a span may lead to orphaned logs if the log references the dropped span.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

## Arguments

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

Expand table

| Name         | Type     | Description                                                        | Default       | Required |
|--------------|----------|--------------------------------------------------------------------|---------------|----------|
| `error_mode` | `string` | How to react to errors if they occur while processing a statement. | `"propagate"` | no       |

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`:

No valid configuration blocks found.

### `output`

Required

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

The following arguments are supported:

Expand table

| Name      | Type                     | Description                           | Default | Required |
|-----------|--------------------------|---------------------------------------|---------|----------|
| `logs`    | `list(otelcol.Consumer)` | List of consumers to send logs to.    | `[]`    | no       |
| `metrics` | `list(otelcol.Consumer)` | List of consumers to send metrics to. | `[]`    | no       |
| `traces`  | `list(otelcol.Consumer)` | List of consumers to send traces to.  | `[]`    | no       |

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:

Expand table

| Name                               | Type      | Description                                          | Default | Required |
|------------------------------------|-----------|------------------------------------------------------|---------|----------|
| `disable_high_cardinality_metrics` | `boolean` | Whether to disable certain high cardinality metrics. | `true`  | no       |

`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.

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

### `logs`

> Note
> 
> The `logs` block is deprecated. Use \[`log_conditions`]\[log\_conditions] instead.

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

Expand table

| Name         | Type           | Description                                    | Default | Required |
|--------------|----------------|------------------------------------------------|---------|----------|
| `log_record` | `list(string)` | List of OTTL statements filtering OTLP metric. |         | no       |

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

- [OTTL log context](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/contexts/ottllog/README.md)

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

### `metrics`

> Note
> 
> The `metrics` block is deprecated. Use \[`metric_conditions`]\[metric\_conditions] instead.

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

Expand table

| Name        | Type           | Description                                               | Default | Required |
|-------------|----------------|-----------------------------------------------------------|---------|----------|
| `datapoint` | `list(string)` | List of OTTL statements filtering OTLP metric datapoints. |         | no       |
| `metric`    | `list(string)` | List of OTTL statements filtering OTLP metric.            |         | no       |

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

- [OTTL metric context](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/contexts/ottlmetric/README.md)
- [OTTL datapoint context](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/contexts/ottldatapoint/README.md)

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`

> Note
> 
> The `traces` block is deprecated. Use \[`trace_conditions`]\[trace\_conditions] instead.

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

Expand table

| Name        | Type           | Description                                         | Default | Required |
|-------------|----------------|-----------------------------------------------------|---------|----------|
| `span`      | `list(string)` | List of OTTL statements filtering OTLP spans.       |         | no       |
| `spanevent` | `list(string)` | List of OTTL statements filtering OTLP span events. |         | no       |

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

- [OTTL span context](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/contexts/ottlspan/README.md)
- [OTTL spanevent context](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/pkg/ottl/contexts/ottlspanevent/README.md)

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.

### `trace_conditions`

The `trace_conditions` block specifies inferred-context OTTL conditions for traces.

Expand table

| Name         | Type           | Description                             | Default | Required |
|--------------|----------------|-----------------------------------------|---------|----------|
| `conditions` | `list(string)` | List of OTTL conditions.                |         | yes      |
| `context`    | `string`       | OTTL context for evaluating conditions. |         | no       |

Supported `context` values are:

- `resource`
- `span`
- `spanevent`

For more details on available contexts, refer to [filterprocessor context documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/processor/filterprocessor#context).

### `metric_conditions`

The `metric_conditions` block specifies inferred-context OTTL conditions for metrics.

Expand table

| Name         | Type           | Description                             | Default | Required |
|--------------|----------------|-----------------------------------------|---------|----------|
| `conditions` | `list(string)` | List of OTTL conditions.                |         | yes      |
| `context`    | `string`       | OTTL context for evaluating conditions. |         | no       |

Supported `context` values are:

- `resource`
- `metric`
- `datapoint`

For more details on available contexts, refer to [filterprocessor context documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/processor/filterprocessor#context).

### `log_conditions`

The `log_conditions` block specifies inferred-context OTTL conditions for logs.

Expand table

| Name         | Type           | Description                             | Default | Required |
|--------------|----------------|-----------------------------------------|---------|----------|
| `conditions` | `list(string)` | List of OTTL conditions.                |         | yes      |
| `context`    | `string`       | OTTL context for evaluating conditions. |         | no       |

Supported `context` values are:

- `resource`
- `log`

For more details on available contexts, refer to [filterprocessor context documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/processor/filterprocessor#context).

`trace_conditions`, `metric_conditions`, and `log_conditions` can’t be used together with `traces`, `metrics`, and `logs` blocks in the same component.

## Exported fields

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

Expand table

| Name    | Type               | Description                                                      |
|---------|--------------------|------------------------------------------------------------------|
| `input` | `otelcol.Consumer` | A value that other components can use to send telemetry data to. |

`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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

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

  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
    logs    = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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.otlphttp.default.input]
    logs    = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}
```

### Drop non-HTTP spans and sensitive logs

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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.otlphttp.default.input]
    logs    = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}
```

## Compatible components

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

- Components that export [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-exporters)

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

- Components that consume [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-consumers)

> 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.