otelcol.processor.filter
otelcol.processor.filter
accepts and filters 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:
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
Note
Raw Alloy syntax strings can be used to write OTTL statements. For example, the OTTL statementattributes["grpc"] == true
is written in Alloy syntax as `attributes[“grpc”] == true`
Note
otelcol.processor.filter
is a wrapper over the upstream OpenTelemetry Collectorfilter
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 is as specific as possible ensure you retain only the data you want to keep.
- 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
otelcol.processor.filter "LABEL" {
output {
metrics = [...]
logs = [...]
traces = [...]
}
}
Arguments
otelcol.processor.filter
supports the following arguments:
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, do not 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
The following blocks are supported inside the definition of
otelcol.processor.filter
:
Hierarchy | Block | Description | Required |
---|---|---|---|
traces | traces | Statements which filter traces. | no |
metrics | metrics | Statements which filter metrics. | no |
logs | logs | Statements which filter logs. | no |
output | output | Configures where to send received telemetry data. | yes |
debug_metrics | debug_metrics | Configures the metrics that this component generates to monitor its state. | no |
traces block
The traces
block specifies statements that filter trace telemetry signals.
Only one traces
block can be specified.
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:
Statements are checked in order from “high level” to “low level” telemetry, in this order:
span
spanevent
If at least one span
condition is satisfied, the spanevent
conditions will not 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.
metrics block
The metrics
block specifies statements that filter metric telemetry signals.
Only one metrics
blocks can be specified.
Name | Type | Description | Default | Required |
---|---|---|---|---|
metric | list(string) | List of OTTL statements filtering OTLP metric. | no | |
datapoint | list(string) | List of OTTL statements filtering OTLP metric datapoints. | no |
The syntax of OTTL statements depends on the OTTL context. See the OpenTelemetry documentation for more information:
Statements are checked in order from “high level” to “low level” telemetry, in this order:
metric
datapoint
If at least one metric
condition is satisfied, the datapoint
conditions will not 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.
logs block
The logs
block specifies statements that filter log telemetry signals.
Only logs
blocks can be specified.
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. See the OpenTelemetry documentation for more information:
Only one of the statements inside the list of statements has to be satisfied.
output block
The output
block configures a set of components to forward resulting telemetry data to.
The following arguments are supported:
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 block
The debug_metrics
block configures the metrics that this component generates to monitor its state.
The following arguments are supported:
Name | Type | Description | Default | Required |
---|---|---|---|---|
disable_high_cardinality_metrics | boolean | Whether to disable certain high cardinality metrics. | true | no |
level | string | Controls 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 tootelcol.exporter.*
andotelcol.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:
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
does not expose any component-specific debug
information.
Debug metrics
otelcol.processor.filter
does not expose any component-specific debug metrics.
Examples
Drop spans which contain a certain span attribute
This example sets the attribute test
to pass
if the attribute test
does not exist.
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]
}
}
Each "
is escaped with \"
inside the Alloy syntax string.
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 amy_label
resource attribute with a value ofabc123
. - The metric is a histogram.
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]
}
}
Some values in the Alloy syntax string are escaped:
\
is escaped with\\
"
is escaped with\"
Drop non-HTTP spans and sensitive logs
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]
}
}
Each "
is escaped with \"
inside the Alloy syntax string.
Some values in the Alloy syntax strings are escaped:
\
is escaped with\\
"
is escaped with\"
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
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.