---
title: Aggregate Processor
description: >-
  Learn how to use the Aggregate processor to combine multiple metrics with the
  same tag values into a single sample.
breadcrumbs: Docs > Observability Pipelines > Processors > Aggregate Processor
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Aggregate Processor
Available for:
{% icon name="icon-metrics" /%}
 Metrics 
## Overview{% #overview %}

The Aggregate processor combines multiple metrics with the same tag values into a single sample based on the selected aggregation mode. Aggregating metrics can help reduce your metric volume and costs.

## Setup{% #setup %}

To set up the Aggregate processor:

1. Define a filter query. See [Metrics Search Syntax](https://docs.datadoghq.com/observability_pipelines/search_syntax/metrics.md) for information on creating queries.
   - Metrics that do not match the filter query are sent to the next step in the pipeline.
   - Metrics that match the query are aggregated and the aggregated metrics are sent to the next step in the pipeline.
1. In the **Mode** dropdown menu, select the aggregation function to use. See the Modes section for details.
1. In the **Interval** field, enter the time window in seconds for aggregating metrics. The maximum value is 60 seconds.

### Optional settings{% #optional-settings %}

**Use event timestamp** is enabled by default and groups metrics into time windows based on each metric's timestamp. Toggle it off to group metrics by when the Worker processes them. See the Grouping by timestamp section for more information.

**Allowed lateness** is available when **Use event timestamp** is enabled. In the **Allowed lateness** field, enter the number of seconds that a time window accepts late metrics after its end time. Enter `0` to drop all late metrics. See the Late metrics section for more information.

**Note**: A longer allowed lateness increases memory usage.

## How the processor works{% #how-the-processor-works %}

### Grouping by timestamp{% #grouping-by-timestamp %}

When **Use event timestamp** is enabled, the processor groups metrics by each metric's timestamp, not by ingestion time (when the Worker processes the metric).

Time windows start at fixed times based on the interval. For example, with a 10-second interval, the first three windows are:

- 12:00:00 to 12:00:10
- 12:00:10 to 12:00:20
- 12:00:20 to 12:00:30

A metric with a timestamp of 12:00:07 goes into the 12:00:00 to 12:00:10 window if the metric arrives within the allowed lateness.

Grouping metrics by timestamp is useful for destinations that use the metric timestamp as a key. For example, Datadog Metrics overwrites earlier values that have the same timestamp. Grouping metrics by timestamp prevents distinct samples from overwriting one another.

#### Late metrics{% #late-metrics %}

The **Allowed lateness** grace period starts at a window's end time and is based on the Worker's system clock. After the grace period ends, the processor closes the window permanently and sends its aggregated metrics. The processor drops any later metrics for that window and counts them in the `pipelines.component_discarded_events_total` metric. See [Pipelines Usage Metrics](https://docs.datadoghq.com/observability_pipelines/monitoring_and_troubleshooting/pipeline_usage_metrics.md) for more information.

For example, with a 10-second interval and an allowed lateness of 5 seconds, the 12:00:00 to 12:00:10 window accepts metrics until 12:00:15 on the Worker's system clock. For a metric with a timestamp of 12:00:07:

- If the metric arrives at 12:00:13, it is added to the 12:00:00 to 12:00:10 window.
- If the metric arrives at 12:00:16, it is dropped because the window closed at 12:00:15.

At 12:00:15, the processor sends the aggregated metrics for the 12:00:00 to 12:00:10 window.

## Modes{% #modes %}

The Aggregate processor can combine metrics into a single metric based on the following modes. Some modes are available only for specific [metric kinds](https://docs.datadoghq.com/observability_pipelines/configuration.md?tab=metrics#metrics-data), incremental or absolute.

| Mode   | Description                                                                            | Incremental metrics | Absolute metrics |
| ------ | -------------------------------------------------------------------------------------- | ------------------- | ---------------- |
| Auto   | Default mode. Sums incremental metrics and uses the latest value for absolute metrics. | yes                 | yes              |
| Sum    | Sums the metric values.                                                                | yes                 |
| Count  | Counts the number of times the metric is received.                                     | yes                 | yes              |
| Latest | Returns the latest metric value.                                                       | yes                 |
| Max    | Returns the maximum metric value.                                                      | yes                 |
| Mean   | Returns the mean metric value.                                                         | yes                 |
| Min    | Returns the minimum metric value.                                                      | yes                 |