Series Aggregate

Analytics Metrics

Synopsis

Merges OTLP metric series over a tumbling window onto a reduced identity, derived by dropping the named attributes.

Schema

- series_aggregate:
    drop_dimensions: <string[]>
    resource_dimensions: <string[]>
    ignore_resource: <boolean>
    window_sec: <numeric>
    gauge: <enum>
    destination: <string>
    pass_through: <boolean>
    max_series: <numeric>
    max_sources_per_series: <numeric>
    filter: <script>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

Field	Required	Default	Description
destination	Y	-	Named target of the route that receives the merged series
drop_dimensions	N	-	Datapoint attribute keys removed before the identity is computed
resource_dimensions	N	-	Resource attribute keys removed before the identity is computed
ignore_resource	N	false	Exclude resource attributes from the identity entirely
window_sec	N	10	Tumbling window length in seconds
gauge	N	"last"	How gauge datapoints landing on the same identity are merged: last, avg, min or max
pass_through	N	false	Also let the source metrics continue down the pipeline. By default they are consumed
max_series	N	10000	Cap on merged series held per window
max_sources_per_series	N	10000	Cap on source series folded into any one merged series
filter	N	-	Cribl-style JavaScript truthiness expression evaluated after if. A falsy result skips the processor
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	See Handling Failures. This does not mean "keep filtering and ignore errors" — see the warning below.
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

warning

ignore_failure: true silently turns this processor off. The drop is signalled to the pipeline as an error value, and the ignore_failure check runs before that value is inspected — so a matched event is kept instead of dropped, no error is logged, and the pipeline reports success. The processor appears to run normally while filtering nothing.

Use it only if you genuinely want a pass-through. To tolerate real errors without losing the filtering, leave ignore_failure unset and handle the failure with on_failure instead.

Details

This is the merging counterpart to Drop Dimensions. That processor removes attributes and leaves the resulting duplicate series as they are; this one removes them and folds the series that become identical into one, over a window.

The attribute lists work the same way as on drop_dimensions, but always as a drop list — there is no keep inversion here.

gauge exists because gauges cannot simply be added. Two datapoints for the same identity are a counter's sum but a gauge's ambiguity: last, average, minimum or maximum are all defensible, so the choice is explicit. The default is last. Sums and counters merge by addition and are unaffected by this setting.

window_sec is a tumbling window: each closes and emits, then the next begins.

Merged series are emitted to destination, a named target of the route, rather than continuing down the pipeline — the same model Aggregate uses, and why destination is required. Set pass_through: true to keep the source metrics flowing as well.

Both caps treat 0 as "use the default", not "unlimited", and a negative value is rejected at load.

Examples

Collapsing Per-Pod Series

Dropping the pod identity and merging what remains...	- series_aggregate: drop_dimensions: ["pod_name", "instance_id"] window_sec: 30 destination: metrics_target
one series per remaining attribute combination, per window:	# http_requests_total{pod_name="api-7f9",route="/v1"} # http_requests_total{pod_name="api-2c1",route="/v1"} # merge into # http_requests_total{route="/v1"} (sums added)

Choosing a Gauge Merge

A gauge needs an explicit rule for combining datapoints...	- series_aggregate: drop_dimensions: ["pod_name"] gauge: max destination: metrics_target
here the worst observed value per window survives the merge:	# memory_usage_ratio{pod_name="api-7f9"} = 0.62 # memory_usage_ratio{pod_name="api-2c1"} = 0.91 # merge, under gauge: max, into # memory_usage_ratio{} = 0.91

Ignoring Resource Level

Removing resource attributes from the identity altogether...	- series_aggregate: ignore_resource: true window_sec: 60 destination: metrics_target pass_through: true
with the source metrics also continuing down the pipeline:	# Series differing only at resource level become one, # and the unmerged metrics still reach the rest of the pipeline.