Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components otelcol otelcol.processor.groupbyattrs

otelcol.processor.groupbyattrs

otelcol.processor.groupbyattrs accepts spans, metrics, and traces from other otelcol components and groups them under the same resource.

We recommend you use the groupbyattrs processor together with otelcol.processor.batch, as a consecutive step. This will reduce the fragmentation of data by grouping records together under the matching Resource/Instrumentation Library.

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

Usage

alloy Copy

otelcol.processor.groupbyattrs "LABEL" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

The following arguments are supported:

keys is a string array that is used for grouping the data. If it is empty, the processor performs compaction and reassociates all spans with matching Resource and InstrumentationLibrary.

Blocks

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

output block

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 block

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

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:

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

Component health

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

Debug information

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

Debug metrics

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

Examples

Grouping metrics

Consider the following metrics, all originally associated to the same Resource:

Copy

Resource {host.name="localhost",source="prom"}
  Metric "gauge-1" (GAUGE)
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-B",id="eth0"}
  Metric "gauge-1" (GAUGE) // Identical to previous Metric
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-B",id="eth0"}
  Metric "mixed-type" (GAUGE)
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-B",id="eth0"}
  Metric "mixed-type" (SUM)
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
  Metric "dont-move" (Gauge)
    DataPoint {id="eth0"}

With the following configuration, the groupbyattrs will re-associate the metrics with either host-A or host-B, based on the value of the host.name attribute.

alloy Copy

otelcol.processor.groupbyattrs "default" {
  keys = [ "host.name" ]
  output {
    metrics = [otelcol.exporter.otlp.default.input]
  }
}

The output of the processor will therefore be:

Copy

Resource {host.name="localhost",source="prom"}
  Metric "dont-move" (Gauge)
    DataPoint {id="eth0"}
Resource {host.name="host-A",source="prom"}
  Metric "gauge-1"
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
  Metric "mixed-type" (GAUGE)
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
  Metric "mixed-type" (SUM)
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
Resource {host.name="host-B",source="prom"}
  Metric "gauge-1"
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
  Metric "mixed-type" (GAUGE)
    DataPoint {id="eth0"}

This output demonstrates how otelcol.processor.groupbyattrs works in various situations:

• The DataPoints for the gauge-1 (GAUGE) metric were originally split under 2 Metric instances and have been merged in the output.
• The DataPoints of the mixed-type (GAUGE) and mixed-type (SUM) metrics have not been merged under the same Metric, because their DataType is different.
• The dont-move metric DataPoints don’t have a host.name attribute and therefore remained under the original Resource.
• The new Resources inherited the attributes from the original Resource (source="prom"), plus the specified attributes from the processed metrics (host.name="host-A" or host.name="host-B").
• The specified “grouping” attributes that are set on the new Resources are also removed from the metric DataPoints.
• While not shown in the above example, the processor also merges collections of records under matching InstrumentationLibrary.

Compaction

Sometimes telemetry data can become fragmented due to multiple duplicated ResourceSpans/ResourceLogs/ResourceMetrics objects. This leads to additional memory consumption, increased processing costs, inefficient serialization and increase of the export requests. In such situations, otelcol.processor.groupbyattrs can be used to compact the data with matching Resource and InstrumentationLibrary properties.

For example, consider this input data:

Copy

Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=1, ...}
  InstrumentationLibrary {name="OtherLibrary"}
  Spans
    Span {span_id=2, ...}
    
Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=3, ...}
    
Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=4, ...}
    
Resource {host.name="otherhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=5, ...}

You can use otelcol.processor.groupbyattrs with its default configuration to compact the data:

alloy Copy

otelcol.processor.groupbyattrs "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input]
  }
}

The output will be:

Copy

Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=1, ...}
    Span {span_id=3, ...}
    Span {span_id=4, ...}
  InstrumentationLibrary {name="OtherLibrary"}
  Spans
    Span {span_id=2, ...}

Resource {host.name="otherhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=5, ...}

Compatible components

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

• Components that export OpenTelemetry otelcol.Consumer

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

• Components that consume OpenTelemetry otelcol.Consumer