> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Metricsgeneration

> OpenTelemetry processor for Metricsgeneration

# Metricsgeneration Processor

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@Aneurysm9](https://github.com/Aneurysm9), [@crobert-1](https://github.com/crobert-1)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/metricsgenerationprocessor)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-alpha-green)

## Overview

## Description

The metrics generation processor (`metricsgeneration`) can be used to create new metrics using existing metrics following a given rule. This processor currently supports the following two rule types for creating a new metric.

1. `calculate`: It can create a new metric from two existing metrics by applying one of the following arithmetic operations: add, subtract, multiply, divide, or percent. One use case is to calculate the `pod.memory.utilization` metric like the following equation-
   `pod.memory.utilization` = (`pod.memory.usage.bytes` / `node.memory.limit`)
2. `scale`: It can create a new metric by scaling the value of an existing metric with a given constant number. One use case is to convert `pod.memory.usage` metric values from Megabytes to Bytes (multiply the existing metric's value by 1,048,576)

## `calculate` Rule Functionality

There are some specific behaviors of the `calculate` metric generation rule that users may want to be aware of:

* The created metric will have the same type as the metric configured as `metric1`.
* If no valid data points are calculated for the metric being created, it will not be created.
  This ensures the processor is not emitting new metrics that are empty.
* Users may want to have metric calculations done on data points whose overlapping attributes match. To enable this
  behavior, please enable the feature gate `metricsgeneration.MatchAttributes`. This feature gate is disabled
  by default, meaning the value used for `metric2` during the calculations is simply the first data point's value.
  Refer to [documentation](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md)
  for more information on how to enable and disable feature gates.

## Configuration

Configuration is specified through a list of generation rules. Generation rules find the metrics which
match the given metric names and apply the specified operation to those metrics.

```yaml theme={null}
processors:
    # processor name: metricsgeneration
    metricsgeneration:

        # specify the metric generation rules
        rules:
              # Name of the new metric. This is a required field.
            - name: <new_metric_name>

              # Unit for the new metric being generated.
              unit: <new_metric_unit>

              # type describes how the new metric will be generated. It can be one of `calculate` or `scale`.  calculate generates a metric applying the given operation on two operand metrics. scale operates only on operand1 metric to generate the new metric.
              type: {calculate, scale}

              # This is a required field. This must be a gauge or sum metric.
              metric1: <first_operand_metric>

              # This field is required only if the type is "calculate". When required, this must be a gauge or sum metric.
              metric2: <second_operand_metric>

              # Operation specifies which arithmetic operation to apply. It must be one of the five supported operations.
              operation: {add, subtract, multiply, divide, percent}
```

## Example Configurations

### Create a new metric using two existing metrics

```yaml theme={null}

rules:
    - name: pod.cpu.utilized
      type: calculate
      metric1: pod.cpu.usage
      metric2: node.cpu.limit
      operation: divide
```

### Create a new metric scaling the value of an existing metric

```yaml theme={null}
# create pod.memory.usage.bytes from pod.memory.usage.megabytes
rules:
    - name: pod.memory.usage.bytes
      unit: Bytes
      type: scale
      metric1: pod.memory.usage.megabytes
      operation: multiply
      scale_by: 1048576
```

## Configuration

### config.yaml (testdata)

```yaml theme={null}
metricsgeneration:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: metric1
      metric2: metric2
      operation: percent
    - name: new_metric
      unit: unit
      type: scale
      metric1: metric1
      scale_by: 1000
      operation: multiply

metricsgeneration/invalid_generation_type:
  rules:
    - name: new_metric
      type: invalid # invalid generation type
      metric1: metric1
      metric2: metric2
      operation: percent

metricsgeneration/invalid_operation:
  rules:
    - name: new_metric
      type: calculate
      metric1: metric1
      metric2: metric2
      operation: invalid # invalid operation type

metricsgeneration/missing_new_metric:
  rules:
    # missing name
    - type: calculate
      metric1: metric1
      metric2: metric2
      operation: percent

metricsgeneration/missing_operand1:
  rules:
    # missing operand1 metric
    - name: new_metric
      type: calculate
      metric2: metric2
      operation: percent

metricsgeneration/missing_operand2:
  rules:
    # missing operand2 metric
    - name: new_metric
      type: calculate
      metric1: metric1
      operation: percent

metricsgeneration/missing_scale_by:
  rules:
    # missing scale_by
    - name: new_metric
      type: scale
      metric1: metric1
      operation: multiply

metricsgeneration/missing_type:
  rules:
    # missing generation type
    - name: new_metric
      metric1: metric1
      metric2: metric2
      operation: percent

metricsgeneration/matching_metric1:
  rules:
    - name: new_metric
      type: scale
      metric1: new_metric
      operation: multiply
      scale_by: 100

metricsgeneration/matching_metric2:
  rules:
    - name: new_metric
      type: calculate
      metric1: original
      metric2: new_metric
      operation: multiply
```

### config.yaml (testdata)

```yaml theme={null}
metricsgeneration/sum_gauge_metric:
  rules:
    - name: system.filesystem.capacity
      unit: bytes
      type: calculate
      metric1: system.filesystem.usage
      metric2: system.filesystem.utilization
      operation: divide
metricsgeneration/sum_gauge_metric_match_attrs:
  rules:
    - name: system.filesystem.capacity
      unit: bytes
      type: calculate
      metric1: system.filesystem.usage
      metric2: system.filesystem.utilization
      operation: divide
```

### config.yaml (testdata)

```yaml theme={null}
metricsgeneration/metric2_zero_add:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: add
      type: calculate
metricsgeneration/metric2_zero_subtract:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: subtract
      type: calculate
metricsgeneration/metric2_zero_multiply:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: multiply
      type: calculate
metricsgeneration/metric2_zero_divide:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: divide
      type: calculate
metricsgeneration/metric2_zero_percent:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: percent
      type: calculate
```

### config.yaml (testdata)

```yaml theme={null}
metricsgeneration/match_attributes_disabled:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: add
      type: calculate
metricsgeneration/match_attributes_enabled:
  rules:
    - name: new_metric
      metric1: capacity.total
      metric2: capacity.used
      operation: add
      type: calculate
```

### config.yaml (testdata)

```yaml theme={null}
metricsgeneration/add_sum_sum:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: sum
      metric2: sum
      operation: add
metricsgeneration/add_gauge_gauge:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: gauge
      metric2: gauge
      operation: add
metricsgeneration/add_gauge_sum:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: gauge
      metric2: sum
      operation: add
metricsgeneration/add_sum_gauge:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: sum
      metric2: gauge
      operation: add
metricsgeneration/multiply_gauge_sum:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: gauge
      metric2: sum
      operation: multiply
metricsgeneration/multiply_sum_gauge:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: sum
      metric2: gauge
      operation: multiply
metricsgeneration/divide_gauge_sum:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: gauge
      metric2: sum
      operation: multiply
metricsgeneration/divide_sum_gauge:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: sum
      metric2: gauge
      operation: divide
metricsgeneration/subtract_gauge_sum:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: gauge
      metric2: sum
      operation: subtract
metricsgeneration/subtract_sum_gauge:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: sum
      metric2: gauge
      operation: subtract
metricsgeneration/percent_gauge_sum:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: gauge
      metric2: sum
      operation: percent
metricsgeneration/percent_sum_gauge:
  rules:
    - name: new_metric
      unit: percent
      type: calculate
      metric1: sum
      metric2: gauge
      operation: percent
```

***

*Last generated: 2026-07-06*