Cumulative to Delta

Overview

The Cumulative to Delta processor converts monotonic, cumulative-temporality metrics (sum, histogram, exponentialhistogram) into delta temporality. Useful when:

• The destination only accepts delta metrics (e.g. some statsd-style backends).
• A downstream rate calculation needs deltas instead of running totals.
• You want to reduce wire size by sending only the increment between scrapes.

The processor maintains state per metric series — it remembers the previous cumulative value to compute the delta. The initial_value setting controls what happens to the first observation after a (re)start.

Supported types: Metrics

Configuration

Parameter	Type	Default	Description
include	object	—	Restrict conversion to specific metrics. When omitted, all eligible metrics are converted. See "Match block" below.
exclude	object	—	Skip specific metrics from conversion. Exclude takes precedence over Include.
max_staleness	duration	1h (upstream default when 0)	How long a metric's prior cumulative value is kept after it was last seen. After this window, the next observation is treated as if it were the first.
initial_value	string	auto	How the first observed point is handled on (re)start. One of auto, keep, drop.

Match block (include / exclude)

Parameter	Type	Default	Description
match_type	string	—	strict (exact name match) or regexp (regex match against metric name). Required when metrics is set.
metrics	string[]	—	List of metric names (or regexes when match_type=regexp) to include / exclude. Required when match_type is set.
metric_types	string[]	—	Restrict by metric type. Subset of ["sum", "histogram", "exponentialhistogram"].

initial_value semantics

Value	Behavior	Best for
auto	Emit the first point only if start_time indicates a fresh counter (process restart).	DaemonSet / gateway deployments where the collector outlives the source — the default.
keep	Always emit the first observed value as the delta.	Sidecar deployments where the collector lifecycle matches the app.
drop	Always store the first value but emit nothing for it. Guarantees every emitted delta was observed at least twice.	When duplicate-on-restart is unacceptable (e.g. metering / billing).

Example Configuration

{
  // Convert only specific cumulative sums to delta
  "include": {
    "match_type": "strict",
    "metrics": ["http.server.request.count", "system.network.bytes"],
    "metric_types": ["sum"],
  },

  // Skip everything matching this regex
  "exclude": {
    "match_type": "regexp",
    "metrics": ["^app\\.internal\\..*"],
  },

  "max_staleness": "30m",
  "initial_value": "drop", // safest for billing / metering metrics
}

Notes

• Stateful. The processor holds per-series state. Memory grows with the cardinality of converted metrics; tune max_staleness to bound it.
• Restart behavior. On collector restart all state is lost. The first observation after restart is governed by initial_value. Pair with the file_storage extension (auto-injected when childCollector.fileStorage.enabled=true in the supervisor's helm chart) if you need state to survive restarts.
• Order matters. Place this processor before any aggregation / batching / sampling that might drop or merge points — those would silently corrupt the delta computation.