Skip to content

fix(registry): default to summation for metrics without an aggregator - #820

Merged
jdmarshall merged 1 commit into
prometheus:mainfrom
chuanghiduoc:fix/aggregator-default-sum
Aug 23, 2026
Merged

fix(registry): default to summation for metrics without an aggregator#820
jdmarshall merged 1 commit into
prometheus:mainfrom
chuanghiduoc:fix/aggregator-default-sum

Conversation

@chuanghiduoc

Copy link
Copy Markdown
Contributor

Problem

Both the README ("Custom metrics are summed across workers by default") and the worker/cluster JSDoc ("or by summation if aggregator is undefined") promise a 'sum' fallback for metrics without an explicit aggregator. Two recent changes broke that contract:

  1. Registry.aggregate() throws 'undefined' is not a defined aggregator. when any snapshot lacks the property — snapshots produced by registerMetric() with a plain object, or hand-written wrappers. This crashes clusterMetrics() / workerMetrics() entirely.
  2. getMetricsAsArray('sum') silently filters those metrics out (aggregator === metric.aggregator is false when the property is missing), so their values are lost on the shutdown-flush path added for workers in ef1cea2.

Reproduction on current main:

const { Registry } = require('prom-client');
Registry.aggregate([
  [{ help: 'h', name: 'm', type: 'gauge', values: [{ value: 5, labels: {} }] }],
]);
// Error: 'undefined' is not a defined aggregator.

and:

const register = new Registry();
new Counter({ name: 'normal', help: 'h', registers: [register] }); // aggregator defaults to 'sum'
register.getMetricsAsArray('sum').length; // 0 if the metric object lacks .aggregator

Note that new Counter({...}) sets aggregator: 'sum' via the Metric constructor default, so built-in metric classes mask the issue; it only surfaces with wrapper/plain-object metrics, which is exactly what the aggregation and shutdown paths produce internally.

Fix

Restore the documented 'sum' fallback in both places (metric.aggregator ?? 'sum').

Testing

  • two new tests in test/registerTest.js: aggregate() sums snapshots without an aggregator; getMetricsAsArray('sum') / getMetricsAsJSON('sum') include them
  • full unit suite: 29 suites / 581 tests passing

Both the README and the worker/cluster JSDoc state that metrics are
summed across workers when no explicit aggregator is configured. Two
regressions broke that contract:

- Registry.aggregate() threw "'undefined' is not a defined aggregator."
  for snapshots lacking the property (e.g. metrics registered via
  registerMetric() with a plain object), which crashes
  clusterMetrics()/workerMetrics() entirely.
- getMetricsAsArray('sum') silently dropped those metrics, so their data
  was lost on the shutdown flush path introduced for workers.

Restore the documented 'sum' fallback in both places.

@jdmarshall jdmarshall left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm.. I had code for this but then convinced myself it wasn't needed. :/

@jdmarshall jdmarshall added this to the v0.16 milestone Aug 23, 2026
@jdmarshall
jdmarshall merged commit e846ce7 into prometheus:main Aug 23, 2026
13 of 15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants