> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rollup rules

> What are rollup rules, and how to create, edit, or delete them.

To downsample and aggregate metrics after they're sent by the client but before
they're stored, create *rollup rules*.

Rollup rules are a type of [aggregation rule](/control/shaping/shape-metrics/rules)
that help you reduce the cardinality footprint of your metrics by dropping raw
data to eliminate unneeded labels. High cardinality footprints can cause slow
dashboards and queries.

If you're working with [late-arriving data](/administer/limits-licensing/limits/metric-limits#late-arriving-metrics),
rollup rules are well suited for ensuring all of your data aggregates the way you
need it.

As an example, `instance` or `pod` labels don't often add value on their own,
but removing these labels from the client side isn't always possible. You can
use rollup rules to avoid storing these labels.

Rollup rules support both Prometheus and Graphite metrics.

## View rollup rules

Select from the following methods to view rollup rules.

<Tabs>
  <Tab title="Web" id="view-a-rollup-rule-web">
    In Palo Alto Networks Cortex XCOR, view rollup rules in the
    [Aggregation rules UI](/control/shaping/shape-metrics/reduce-cardinality/aggregation-rules).
  </Tab>

  <Tab title="Chronoctl" id="view-a-rollup-rule-chronoctl">
    To list only rollup rules on the command line with [Chronoctl](/tooling/chronoctl),
    use this command:

    ```shell theme={null}
    chronoctl rollup-rules list
    ```
  </Tab>

  <Tab title="API" id="view-a-rollup-rule-api">
    To complete this action with the Cortex XCOR API, use the
    [`ListRollupRules`](/tooling/api-info/definition/operations/ListRollupRules) endpoint.

    Because the Cortex XCOR API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Cortex XCOR instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

For information about viewing, copying, or downloading rule configurations, see
[Rule configuration](/control/shaping/shape-metrics/reduce-cardinality/aggregation-rules#rule-configuration).

## Create a rollup rule

Select from the following methods to apply rollup rules. Cortex XCOR
doesn't limit the number of rollup rules a system can have.

<Note>
  If you define a rollup rule using the Cortex XCOR app, you must download
  the rule configuration and apply it with one of the supported methods.
</Note>

<Tabs>
  <Tab title="Web" id="create-a-rollup-rule-web">
    Create rollup rule configurations in Cortex XCOR from the
    [Aggregation rules UI](/control/shaping/shape-metrics/reduce-cardinality/aggregation-rules).

    When creating a rule configuration, the **Visual Editor** displays by default.
    When creating a rule in Live Telemetry Analyzer, the dialog pre-populates fields based
    on the user's selected data.

    To create a rule configuration:

    1. Enter or edit data for the following fields:
       * **Rule Name**: Add or edit the name of the rule.
       * **Rule Details**: Either **Rule Preview** or **Rule Enabled**. See
         [rule mode](#rule-mode) for more information.
       * **Matching Time Series:** Time series the rule applies to. You must include a
         **Label**, operator (`=` or `!=`), and a **Value**. The value you enter maps to
         the [`filters`](#filters) section of the
         [CreateRollupRule](/tooling/api-info/definition/operations/CreateRollupRule#body-rollup-rule-filters)
         endpoint.

         For example, if you want the rollup rule to match on
         [Prometheus gauge metrics](/control/shaping/shape-metrics/types#prometheus), enter
         `__m3_prom_type__` as the label to match on, and `gauge` as the value. The
         resulting filter looks like:

         ```text theme={null}
         __m3_prom_type__ = gauge
         ```

         Values accept a comma-separated list and
         [glob syntax](/investigate/querying/glob-syntax), including matching multiple
         patterns with an `OR`, such as `service:{svc1,svc2}`. Click <Icon icon="plus" /> **Add**
         to add another time series.
       * **Labels to Roll Up**: **Discard Labels** or **Keep Labels**. Add labels to the
         **Input Labels** text box.
       * **Output Metric**: The new metric's name and aggregation configuration.
         * **Output Metric Name:** Edit the output metric name. Clear the checkbox for
           **Include metric name** to remove the original name.

         * **Input Metric Type:** Select a
           [metric type](/control/shaping/shape-metrics/types#cortex-xcor-types), which
           determines how the rollup rule interprets all matching data points. For
           example, if you select **Gauge**, the rollup rule interprets all matching
           data points as that data type, even if the original source isn't a gauge
           metric. This behavior means that the metric type you choose doesn't have to
           match the data type of the incoming data.

           If you want to match the incoming metric to a specific type, enter two
           matching time series in the rollup rule: one to match the metric, and
           another to match the metric type. Use `__metric_type__` to define the type
           of metric you want to match on. For example, if you want to match a time
           series named `agg_write_latency` that's a cumulative exponential histogram,
           define two series that look like:

           ```text theme={null}
           __name__ = agg_write_latency AND __metric_type__ = cumulative_exponential_histogram
           ```

         * **Aggregation:** Select an [aggregation operation](#aggregation-operations).

         * **Aggregation Interval:** The length of time between samples. See
           [Aggregation interval](#aggregation-interval).
       * **Raw Data**: Turn on **Drop raw input data** to remove the raw input data
         after aggregation.
    2. When finished, click **Code config**.
    3. Choose your rule creation method from these options:
       * **Chronoctl**
       * **Terraform**
       * **API**
    4. Apply the changes based on your selected method.
  </Tab>

  <Tab title="Chronoctl" id="create-a-rollup-rule-chronoctl">
    To create a rollup rule with [Chronoctl](/tooling/chronoctl), define the rule in a
    YAML file and apply it.

    If you don't already have a YAML configuration file, use the `scaffold` Chronoctl
    parameter to generate a template for a specific resource type:

    ```shell theme={null}
    chronoctl rollup-rules scaffold
    ```

    You can redirect the results (using the redirection operator `>`) to a file for
    editing.

    1. Create or edit a YAML configuration file to configure the rollup rule.

    2. Apply the rollup rule:

       ```shell /FILE_NAME/ theme={null}
       chronoctl apply -f FILE_NAME.yaml
       ```

    Replace *`FILE_NAME`* with the name of the YAML configuration file.

    See the [Chronoctl rollup rule example](#chronoctl-rollup-rule-example) for more
    information.
  </Tab>

  <Tab title="Terraform" id="create-a-rollup-rule-terraform">
    <Note>
      When you run `terraform plan` to generate an execution plan, Cortex XCOR automatically
      tests configurations that include notification policies by submitting them as dry runs.
      For details, see the
      [Terraform provider](/tooling/infrastructure/terraform#validate-plans-with-dry-runs)
      documentation.
    </Note>

    Create a rollup rule with Terraform by using the `chronosphere_rollup_rule`
    type, followed by a name in a resource declaration. See the
    [Terraform rollup rule example](#terraform-rollup-rule-example) for more information.

    1. Add the definition to a Terraform file.
    2. Run this command to create the resource:

       ```shell theme={null}
       terraform apply
       ```
  </Tab>

  <Tab title="API" id="create-a-rollup-rule-api">
    To complete this action with the Cortex XCOR API, use the
    [`CreateRollupRule`](/tooling/api-info/definition/operations/CreateRollupRule) endpoint.

    Because the Cortex XCOR API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Cortex XCOR instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

Rollup rules take effect immediately, but can require a full
[aggregation interval](#aggregation-interval) to show a change.

### Best practices for rule creation

Following these guidelines helps ensure your rollup rules work as intended:

* Use [Live Telemetry Analyzer](/investigate/analyze/telemetry-analyzer) to verify your
  [glob syntax](/investigate/querying/glob-syntax) to ensure your query matches
  the correct metrics.
* Before using a rollup rule to group labels, be sure those labels aren't used
  in other places, such as dashboards, monitors, or the queries you use to
  debug issues.
* A dash (`-`) inside square brackets is a range operator, not a literal character.
  The filter `service_cluster:[a-d]` matches a single character from `a` through `d`.
  To match a value that contains a literal dash, use curly braces, which take a
  comma-separated list of alternatives and treat a dash as an ordinary character. For
  example: `service_cluster:{my-label,other-label}`.
* Metrics can match more than one rule. Matching multiple rules can affect data
  retention. If a rule matches any `drop_raw=true`, raw metrics are dropped.
* If a single output series receives more than 10 million unique input series,
  Cortex XCOR might stop accepting new input series specified in the
  rollup rule, which could result in partially aggregated metrics. To avoid this
  behavior, choose a [label policy](#label-policies) that writes more output series
  by removing fewer labels.

```mermaid actions={false} theme={null}
---
title: Raw data persistence flowchart
---
flowchart LR
accTitle: Raw data persistence flowchart
accDescr: This flowchart shows how metrics matching multiple rules can have unexpected data persistence.
R1[Rule 1]-->DRT[drop<br>raw=true]
R2[Rule 2]-->DRT
R3[Rule 3]-->DRF[drop<br>raw=false]
ExRule[sample_metric<br>with<br>label=test]-->|matches| R1
ExRule-->|matches| R3
ER[End result is<br>raw data drops<br>and aggregated<br>data persists]
DRT-->|Raw data<br>dropped| ER
DRF-->|Raw data<br>persisted| ER
```

### Chronoctl rollup rule example

Here's an example of a rollup rule that matches time series with the value
`permits_blocked`, while discarding any labels matching `instance` and `job`. It uses
a cumulative counter type metric, and aggregates as a sum using a 30-second interval.

```yaml Chronoctl example icon="square-terminal" theme={null}
api_version: v1/config
kind: RollupRule
spec:
  slug: permits_blocked_without_instance
  name: permits blocked without instance
  filters:
    - name: __name__
      value_glob: permits_blocked
  metric_name: '{{ .MetricName }}:without_instance'
  metric_type: CUMULATIVE_COUNTER
  aggregation: SUM
  interval: 30s
  label_policy:
    discard:
    - instance
    - job
  add_metric_type_label: true
  mode: ENABLED
```

### Terraform rollup rule example

Here's an example of a rollup rule that matches time series with the value
`permits_blocked`, while discarding any labels matching `instance` and `job`.
It uses a cumulative counter type metric, and aggregates as a sum using a 30-second interval.

```terraform Terraform example icon="square-terminal" theme={null}
resource "chronosphere_rollup_rule" "permits_blocked_without_instance" {
  name      = "permits blocked without instance"
  slug      = "permits_blocked_without_instance"
  filter    = "__name__:permits_blocked"
  metric_type = "CUMULATIVE_COUNTER"
  aggregation = "SUM"
  interval = "30s"
  exclude_by  = ["instance", "job"]
  metric_type_tag = true
  mode      = "ENABLED"
  new_metric  = "{{ .MetricName }}:without_instance"
}
```

## Delete a rollup rule

<Tabs>
  <Tab title="Chronoctl" id="delete-a-rollup-rule-chronoctl">
    To delete rollup rules with [Chronoctl](/tooling/chronoctl), use this command:

    ```shell /SLUG/ theme={null}
    chronoctl rollup-rules delete SLUG
    ```

    Replace *`SLUG`* with the rule's slug.

    For example, to delete the `http_request_duration_by_service_and_status` rule,
    use this command:

    ```shell theme={null}
    chronoctl rollup-rules delete http_request_duration_by_service_and_status
    ```

    If your slug starts with a dash (`-`), use double quotes (`"`) around the slug
    name.

    ```shell theme={null}
    chronoctl rollup-rules delete "-my-rollup-rule"
    ```
  </Tab>

  <Tab title="Terraform" id="delete-a-rollup-rule-terraform">
    To delete a resource that's managed by [Terraform](/tooling/infrastructure/terraform):

    1. Edit your Terraform configuration file to remove the pre-existing resource
       definition.
    2. Run this command to remove the resource from Cortex XCOR:

       ```shell theme={null}
       terraform apply
       ```
  </Tab>

  <Tab title="API" id="delete-a-rollup-rule-api">
    To complete this action with the Cortex XCOR API, use the
    [`DeleteRollupRule`](/tooling/api-info/definition/operations/DeleteRollupRule) endpoint.

    Because the Cortex XCOR API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Cortex XCOR instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

## Rollup rule attributes

To accurately aggregate your data, rollup rules require you to both configure
multiple fields and to have an understanding of
[aggregation operations](#aggregation-operations).

See the [CreateRollupRule API](/tooling/api-info/definition/operations/CreateRollupRule)
documentation for the complete list of fields that are part of the `rollup_rule`
object that you define when [creating a rollup rule](#create-a-rollup-rule) with any
of the supported methods.

### Filters

The `filters` field selects the incoming metrics a rule applies to. Each entry
matches one label name against a value, and a metric must match every entry to match
the rule. Values support [glob syntax](/investigate/querying/glob-syntax), including
matching multiple patterns with an `OR`, such as `service:{svc1,svc2}`.

Synthetic labels match on request metadata instead of on a metric's label.
The following table lists the synthetic labels that a rollup rule filter most often
matches on, and the values each one accepts:

| Filter | Matches | Valid values |
| - | - | - |
| `__metric_type__` | The [metric type](/control/shaping/shape-metrics/types#cortex-xcor-types). Use this filter to match on metric type. | `cumulative_counter`, `cumulative_exponential_histogram`, `delta_counter`, `delta_exponential_histogram`, `gauge`, `measurement` |
| `__metric_source__` | The [source format](/control/shaping/shape-metrics/types#supported-formats) the metric arrived in. | `carbon`, `chrono_azure`, `chrono_cloudflare`, `chrono_gcp`, `chrono_integration`, `cloudwatch_metric_stream`, `dogstatsd`, `open_metrics`, `open_telemetry`, `prometheus`, `signalfx`, `statsd`, `tagged_statsd`, `wavefront` |
| `__m3_prom_type__` | The [Prometheus metric type](/control/shaping/shape-metrics/types#prometheus), for data ingested with Prometheus. | `counter`, `gauge`, `histogram`, `gauge_histogram`, `summary`, `info`, `state_set` |
| `__otel_type__` | The [OpenTelemetry metric type](/control/shaping/shape-metrics/types#opentelemetry), for data ingested with OpenTelemetry. | `sum`, `monotonic_sum`, `gauge`, `histogram`, `exp_histogram`, `summary` |

For example, the following filter matches any cumulative counter that carries a
`service=gateway` label and whose metric name starts with `http_requests_`:

```text theme={null}
__metric_type__:cumulative_counter service:gateway __name__:http_requests_*
```

### Aggregation interval

The `interval` field sets the amount of time between the aggregated data points a
rule produces. If you omit it, the rule uses the default resolution from your
[retention policy](/administer/limits-licensing/licensing).

An interval must match a resolution that your tenant can write aggregated data to,
typically `15s`, `30s`, or `60s`.

### Rule mode

The `mode` field controls whether a rule aggregates data. It accepts two values:

* `ENABLED`: Aggregates incoming data according to the rule configuration. A rule
  that omits `mode` uses this value.
* `PREVIEW`: Reports the rule's estimated impact without changing stored data. For
  the preview workflow, see
  [Preview a rule's shaping impact](/control/shaping/shape-metrics/reduce-cardinality/shaping-impact).

### Conflicting output metric names

Set `skip_on_conflict` to `true` to skip a rule when another rollup rule already
produces a metric with the same output name. Use this field to write a rule that
produces a series only when no other rule produces one under that name. Default:
`false`.

### Label policies

Use label policies to define which labels to preserve in the resulting metric. In the
rollup rule definition, add the appropriate field to specify which labels to retain
or discard. Most rollup rules must set one of these fields, and no rule can set both.

Neither field accepts `__name__`. A rollup rule can't group by the metric name or
drop it. To change the output metric's name, use `metric_name` instead.

<Note>
  Rules that set `graphite_label_policy` can't set `keep` or `discard`, their Terraform
  equivalents `group_by` and `exclude_by`, or `metric_name`. Manage Graphite positional
  labels with [`graphite_label_policy.replace`](#set-a-graphite-label-policy) instead.
</Note>

#### Keep specified labels

To aggregate only metrics that contain *all* of the specified labels and discard all
other labels, use `group_by` (Terraform) or `keep`. When using these rollup rules,
you must specify the labels to aggregate the metrics by. If a metric doesn't include
all of the specified labels, the metric isn't included in the rule.

If a rollup rule uses `group_by` or `keep`, the rule will match only metrics with
labels that contain these fields, even if the label `filters` would have matched
these metrics.

A rule that uses `group_by` or `keep` also constrains its own [filters](#filters).
The filters must include a `__name__` entry, and that entry can't contain a wildcard,
so the rule targets one metric name instead of an arbitrary set. Adding the
`{{ .MetricName }}` template to `metric_name` lifts both restrictions, because the
output name then varies with each matched metric.

#### Remove specified labels

To target a group of metrics for a particular service, team, or other higher-level
set of metrics, use `exclude_by` (Terraform) or `discard`. When using these rollup
rules, you specify which labels to remove from the aggregated metric, while keeping
all other labels.

#### Set a Graphite label policy

For Graphite metrics, you can use the `graphite_label_policy` parameter to also
set a Graphite-specific label policy. This lets you define replacements for label
values without changing their positions, which can reduce cardinality without breaking
Graphite metrics' preferred positional indexing.

For example, assume you have raw metric names that follow this pattern:

```text theme={null}
cluster.production.instance.instance1.requests_count
cluster.production.instance.instance2.requests_count
...
```

You can create a Graphite label policy that defines a replacement rule that replaces
the third positional label name (`__g3__`) with a new string value (`INSTANCE`).

This replacement aggregates these metrics as
`cluster.production.instance.INSTANCE.requests_count`, without changing their positional
indexing.

<Tabs>
  <Tab title="Chronoctl" id="graphite-label-policy-chronoctl">
    The output of the `chronoctl rollup-rules scaffold` command includes the `graphite_label_policy`
    parameter:

    ```yaml Chronoctl example icon="square-terminal" theme={null}
    api_version: v1/config
    kind: RollupRule
    spec:
      # ...
      graphite_label_policy:
        # List of labels to replace. Use to discard high-cardinality values while still
        # preserving the original positions of the Graphite metric.
        replace:
          - # Name of the label to replace the value for. Only positional Graphite labels
            # such as '__gX__' are allowed.
            name: <string>
            # New value of the replaced label.
            new_value: <string>
      # ...
    ```

    To implement the rule from the example scenario as a Chronoctl YAML resource, define
    the `name` and `new_value` in the list of `replace` values:

    ```yaml Chronoctl example icon="square-terminal" theme={null}
    api_version: v1/config
    kind: RollupRule
    spec:
      # ...
      graphite_label_policy:
        replace:
          - name: "__g3__"
            new_value: "INSTANCE"
      # ...
    ```

    Define multiple replacements in a single rollup rule by adding more pairs of `name`
    and `new_value` to the `replace` list.
  </Tab>

  <Tab title="Terraform" id="graphite-label-policy-terraform">
    The `graphite_label_policy` block in the `chronosphere_rollup_rule` resource contains
    a `replace` block with `name` and `new_value` arguments.

    For example, to implement the rule from the example scenario as a Terraform resource:

    ```terraform Terraform example icon="square-terminal" theme={null}
    resource "chronosphere_rollup_rule" "rollup_rule" {
      # ...
      graphite_label_policy {
        replace {
          name      = "__g3__"
          new_value = "INSTANCE"
        }
      }
      # ...
    }
    ```
  </Tab>
</Tabs>

### Aggregation operations

Some operations can change the type of the metric during aggregation. The
resulting metric type of an aggregation is called the *output* metric type.

Even if you are ingesting data with the wrong metric type, configure your rollup rule
with the metric type that the ingested data should be. For example, if Cortex XCOR
ingests metrics with type `GAUGE`, but the values actually
represent `DELTA_COUNTER`, use a `metric_type=DELTA_COUNTER` rollup rule to aggregate
them.

Rollup rules support the following aggregation operations:

#### `CUMULATIVE_COUNTER`

Cumulative counters support these aggregations:

* `SUM`: Takes the increase of each individual input series within the
  configured interval, then sums the increases together according to the configured label
  policy. The output is the cumulative summed increase across all input series.

* `COUNT`: Counts the number of unique input series matched by the configured label
  policy (for example, cardinality).

The output type of all cumulative counter aggregations is a [`CUMULATIVE_COUNTER`](/control/shaping/shape-metrics/types#cumulative-counter).

#### `GAUGE`

Gauges support the following aggregation methods:

* `SUM`: Takes the max value of each individual input series within the
  configured interval, then sums all final values together by the configured
  label policy.

* `COUNT`: Counts the number of unique input series matched by the configured label
  policy (for example, cardinality).

* `MIN`: Takes the minimum value of all data points within the configured
  interval across all series matched by the configured label policy.

* `MAX`: Takes the maximum value of all data points within the configured
  interval across all series matched by the configured label policy.

* `PXX`, `MEAN`, `MEDIAN`, `STDEV`, `SUMSQ`: Takes the maximum value of each
  individual input series within the configured interval, and then computes the
  value distribution.

The output type of all gauge aggregations is a [`GAUGE`](/control/shaping/shape-metrics/types#gauge).

When querying a gauge metric with a range vector included in the query
downsampling might impact the accuracy of the query result. Most use cases that
fit this criteria can be converted to use counters instead, which avoids the issue.

#### `DELTA_COUNTER`

Supported aggregations:

* `SUM`: Sums all values of all series matched by the configured label policy. All
  values must be nonnegative.

* `COUNT`: Counts the number of unique input series matched by the configured label
  policy, such as cardinality. Adding more samples to an existing series
  doesn't change the count. Only new series impact the count.

* `COUNT_SAMPLES`: Counts the number of input samples matched by the configured label
  policy. Every sample increments the count, even when multiple samples land on the
  same series.

The output type of all delta counter aggregations is a [`DELTA_COUNTER`](/control/shaping/shape-metrics/types#delta-counter).

A `DELTA_COUNTER` rule treats three settings as a single group: `metric_name`,
`aggregation`, and the label policy, which is exactly one of `keep` or `discard`.
Either set all three or omit all three. Setting any one of the three makes the other
two required.

Omitting all three aggregates matching series as a `SUM`, keeps the original metric
name, and retains every label. The effect is to downsample the counter to the rule's
interval without otherwise changing the series, which is what you want when you need
a coarser resolution and nothing else.

`MEASUREMENT` and `DELTA_EXPONENTIAL_HISTOGRAM` rules can also omit `metric_name` and
the label policy, but both types require an `aggregation`.

Every rollup rule requires a `name`. The `name` field identifies the rule itself, and
is distinct from `metric_name`, which names the output metric.

#### `MEASUREMENT`

A key feature of `MEASUREMENT` aggregations lies in how they treat individual
samples. Unlike other types such as [`GAUGE`](/control/shaping/shape-metrics/rules/rollup#gauge)
and [`CUMULATIVE_COUNTER`](/control/shaping/shape-metrics/rules/rollup#cumulative_counter),
`MEASUREMENT` metrics aggregate all at once, across all samples of your matching
time series within the aggregated time interval. This enables calculation of
accurate statistics server-side, within Cortex XCOR.

A typical use case for `MEASUREMENT` aggregations is calculating statistics across
raw request latencies across all instances. This can be correctly performed through
`metric_type=MEASUREMENT` and `aggregation=P95`. Using `metric_type=GAUGE` in this
scenario produces results you don't want, discarding all samples except the
per-instance max value, then computing the ninety-fifth percentile across these
per-instance max values.

Every `MEASUREMENT` rule must set `drop_raw` to `true`. Cortex XCOR
rejects a `MEASUREMENT` rule that retains its raw input data.

Measurements support the following aggregation methods:

* `SUM`: Sums all values of all series matched by the configured label policy. All
  values must be nonnegative. The output metric type is a
  [`DELTA_COUNTER`](/control/shaping/shape-metrics/types#delta-counter).

* `COUNT_SAMPLES`: Counts the number of input samples matched by the configured label
  policy. The output metric type is a
  [`DELTA_COUNTER`](/control/shaping/shape-metrics/types#delta-counter).

* `SUMSQ`: Sums the squares of all values of all series matched by the configured
  label policy. The output metric type is a
  [`DELTA_COUNTER`](/control/shaping/shape-metrics/types#delta-counter).

* `LAST`: Takes the last value of all samples matched by the configured label policy.
  The output metric type is a [`GAUGE`](/control/shaping/shape-metrics/types#gauge).

* `MIN`: Takes the minimum value of all samples matched by the configured label
  policy. The output metric type is a [`GAUGE`](/control/shaping/shape-metrics/types#gauge).

* `MAX`: Takes the maximum value of all samples matched by the configured label
  policy. The output metric type is a [`GAUGE`](/control/shaping/shape-metrics/types#gauge).

* `PXX`, `MEAN`, `MEDIAN`, `STDEV`: Computes the value distribution across all
  samples matched by the configured label policy. The output metric type is a
  [`GAUGE`](/control/shaping/shape-metrics/types#gauge).

* `HISTOGRAM`: Summarizes the distribution of values as an exponential histogram
  with a starting scale of 5. The output type is a
  [`DELTA_EXPONENTIAL_HISTOGRAM`](/control/shaping/shape-metrics/types#delta-exponential-histograms).

### Histograms aggregation operations

<Note>
  If either the input histogram or resulting aggregation exceeds the 160-bucket limit,
  Cortex XCOR decreases the exponential histogram scale until the bucket
  count is within the limit. Downscaling reduces the exponential histogram's resolution.
</Note>

#### `CUMULATIVE_EXPONENTIAL_HISTOGRAM`

Cumulative exponential histogram aggregations operate on OpenTelemetry exponential
histograms with cumulative temporality, and on Prometheus native histograms with
an exponential bucket layout.

Cumulative exponential histograms support this aggregation method:

* `SUM`: Merges input cumulative exponential histograms by the configured label
  policy. The output metric type is a
  [`CUMULATIVE_EXPONENTIAL_HISTOGRAM`](/control/shaping/shape-metrics/types#cumulative-exponential-histograms).

#### `DELTA_EXPONENTIAL_HISTOGRAM`

Delta exponential histogram aggregations operate on OpenTelemetry exponential histograms
with delta temporality.

Delta exponential histograms support this aggregation method:

* `SUM`: Merges input delta exponential histograms by the configured label policy.
  The output metric type is a
  [`DELTA_EXPONENTIAL_HISTOGRAM`](/control/shaping/shape-metrics/types#delta-exponential-histograms).


## Related topics

- [UpdateRollupRule](/tooling/api-info/definition/operations/UpdateRollupRule.md)
- [CreateRollupRule](/tooling/api-info/definition/operations/CreateRollupRule.md)
- [ReadRollupRule](/tooling/api-info/definition/operations/ReadRollupRule.md)
- [ListRollupRules](/tooling/api-info/definition/operations/ListRollupRules.md)
- [DeleteRollupRule](/tooling/api-info/definition/operations/DeleteRollupRule.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.