Cumulativetodelta Processor

Available in: contrib, k8s Maintainers: @TylerHelmuth Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Configuration

Configuration is specified through a list of metrics. The processor uses metric names to identify a set of cumulative metrics and converts them from cumulative to delta. The following settings can be optionally configured:

include: List of metrics names (case-insensitive), patterns or metric types to convert to delta. Valid values for metric types are: sum, histogram, exponentialhistogram.
exclude: List of metrics names (case-insensitive), patterns or metric types to not convert to delta. If a metric name matches both include and exclude, exclude takes precedence. Valid values for metric types are: sum, histogram, exponentialhistogram.
max_staleness: The total time a state entry will live past the time it was last seen. Set to 0 to retain state indefinitely. Default: 1 hour
initial_value: Handling of the first observed point for a given metric identity. When the collector (re)starts, there’s no record of how much of a given cumulative counter has already been converted to delta values.
- auto (default): Send if and only if the startime is set AND the starttime happens after the component started AND the starttime is different from the timestamp. Suitable for gateway deployments, this heuristic is like drop, but keeps values for newly started counters (which could not have had previous observed values).
- keep: Send the observed value as the delta value. Suitable for when the incoming metrics have not been observed before, e.g. running the collector as a sidecar, the collector lifecycle is tied to the metric source.
- drop: Keep the observed value but don’t send. Suitable for gateway deployments, guarantees that all delta counts it produces haven’t been observed before, but loses the values between thir first 2 observations.

If neither include nor exclude are supplied, no filtering is applied.

Examples

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:

        # list the exact cumulative sum or histogram metrics to convert to delta
        include:
            metrics:
                - <metric_1_name>
                - <metric_2_name>
                .
                .
                - <metric_n_name>
            match_type: strict

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:

        # Convert all sum metrics
        include:
            metric_types:
              - sum

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:

        # Convert cumulative sum or histogram metrics to delta
        # if and only if 'metric' is in the name
        include:
            metrics:
                - ".*metric.*"
            match_type: regexp

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:

        # Convert cumulative sum metrics to delta
        # if and only if 'metric' is in the name
        include:
            metrics:
                - ".*metric.*"
            match_type: regexp
            metric_types:
              - sum

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:

        # Convert cumulative sum or histogram metrics to delta
        # if and only if 'metric' is not in the name
        exclude:
            metrics:
                - ".*metric.*"
            match_type: regexp

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:

        # Convert cumulative sum metrics with 'metric' in their name,
        # but exclude histogram metrics
        include:
            metrics:
                - ".*metric.*"
            match_type: regexp
        exclude:
          metric_types:
            - histogram

processors:
    # processor name: cumulative_to_delta
    cumulative_to_delta:
        # If include/exclude are not specified
        # convert all cumulative sum or histogram metrics to delta

Troubleshooting

When Telemetry is enabled, this component can export several metrics. All metrics are disabled by default and must be opted-in via the collector’s service.telemetry.metrics.level configuration.

Warnings

Statefulness: The cumulative_to_delta processor’s calculates delta by remembering the previous value of a metric. For this reason, the calculation is only accurate if the metric is continuously sent to the same instance of the collector. As a result, the cumulative_to_delta processor may not work as expected if used in a deployment of multiple collectors. When using this processor it is best for the data source to being sending data to a single collector.

Attributes

Attribute Name	Description	Type	Values
`metric_type`	The pdata metric type of the datapoint.	string	`sum`, `histogram`, `exponential_histogram`
`reason`	The reason a datapoint was dropped instead of converted.	string	`reset`, `initial`, `bucket_mismatch`

Configuration

Example Configuration

cumulative_to_delta:
  include:
    match_type: strict
    metrics:
      - metric1
      - metric2
  exclude:
    match_type: strict
    metrics:
      - metric3
      - metric4
  max_staleness: 10s

cumulative_to_delta/empty:

cumulative_to_delta/missing_match_type:
  include:
    metrics:
      - metric1
      - metric2
  exclude:
    metrics:
      - metric3
      - metric4

cumulative_to_delta/missing_name:
  include:
    match_type: strict
    metrics:
  exclude:
    match_type: strict
    metrics:

cumulative_to_delta/regexp:
  include:
    match_type: regexp
    metrics:
      - a*
  exclude:
    match_type: regexp
    metrics:
      - b*
  max_staleness: 10s

cumulative_to_delta/metric_type_filter:
  include:
    match_type: regexp
    metrics:
      - a*
    metric_types:
      - sum
  exclude:
    match_type: regexp
    metrics:
      - b*
    metric_types:
      - histogram
  max_staleness: 10s

cumulative_to_delta/invalid_include_metric_type_filter:
  include:
    match_type: regexp
    metrics:
      - a*
    metric_types:
      - gauge
  exclude:
    match_type: regexp
    metrics:
      - b*
    metric_types:
      - histogram
  max_staleness: 10s

cumulative_to_delta/invalid_exclude_metric_type_filter:
  include:
    match_type: regexp
    metrics:
      - a*
  exclude:
    match_type: regexp
    metrics:
      - b*
    metric_types:
      - Invalid
  max_staleness: 10s

cumulative_to_delta/auto:
  initial_value: auto

cumulative_to_delta/keep:
  initial_value: keep

cumulative_to_delta/drop:
  initial_value: drop

Last generated: 2026-08-24

​Cumulativetodelta Processor

​Supported Telemetry

​Overview

​Configuration

​Examples

​Troubleshooting

​Warnings

​Attributes

​Configuration

​Example Configuration

Cumulativetodelta Processor

Supported Telemetry

Overview

Configuration

Examples

Troubleshooting

Warnings

Attributes

Configuration

Example Configuration