feat(metrics): Add native histograms and Prometheus protobuf exposition by ethanolchik · Pull Request #856 · prometheus/client_js

ethanolchik · 2026-09-10T16:49:18Z

Applications currently cannot expose native histogram samples from this client. This adds opt-in native collection to Histogram and the Prometheus protobuf exposition needed to scrape it.

Fixes #576.

const registry = new client.Registry(
  client.Registry.PROMETHEUS_PROTOBUF_CONTENT_TYPE,
);
const histogram = new client.Histogram({
  name: 'request_duration_seconds',
  help: 'Request duration',
  nativeHistogramBucketFactor: 1.1,
  buckets: [],
  registers: [registry],
});

Existing histogram configurations retain classic behavior. Native histograms can retain explicit classic buckets for migration, or use buckets: [] for native-only protobuf output. Protobuf registry methods return a Buffer, represented as Uint8Array in the public TypeScript declarations.

The implementation includes:

Standard exponential schemas -4 through 8, positive and negative sparse buckets, a configurable zero bucket, and native exemplars. The default budget of 160 populated buckets reduces resolution as needed and remains a soft limit at schema -4.
Native JSON snapshots and sum, first, and omit aggregation through registries, clusters, and workers, including reconciliation of different schemas and zero thresholds.
Protobuf encoding for native histograms and existing metric types. protobufjs/light uses the checked-in lib/metrics.json descriptor; lib/metrics.proto and npm run generate-protobuf make its source and regeneration available.
Public types, regression tests, configuration and migration documentation, a runnable HTTP example, and changelog entries.

Validation performed locally:

761 tests in 34 suites passed on Node 22.23.2, 24.21.0, and 26.4.0. The configured Bun CI command also passed.
The Linux check workflow passed through act on Node 24.21.0: ESLint, Prettier, and TypeScript.
npm run benchmarks completed on macOS/Node 26.4.0. A focused registry comparison against upstream, with increased sampling, found no significant regression above a 5% threshold; default-label cases measured roughly 2–4% overhead.
Manual interoperability checks with Prometheus 3.12.0 covered native counts, sums, quantiles, signed and empty histograms, worker aggregation, classic coexistence, and other metric types.
Protobuf descriptor regeneration matched the checked-in file, and the package dry run included the runtime schema and implementation files.

The existing benchmark suite covers classic metrics. Dedicated native workload benchmarks and application-specific rollout validation remain follow-up work. Applications select the protobuf response format themselves; HTTP Accept negotiation is outside this change.

Developed with AI assistance (Codex), also disclosed in the commit trailer.

Extend Histogram with opt-in exponential native buckets, exemplars, and resolution reduction. Preserve native snapshots through registry, worker, and cluster aggregation. Add protobuf exposition for all existing metric types, binary registry return types, schema generation, documentation, and an HTTP example. Fixes prometheus#576 Assisted-by: Codex Signed-off-by: Ethan Olchik <eolchik@cloudflare.com>

jdmarshall · 2026-09-11T20:17:13Z


 class Histogram extends Metric {
 	constructor(config) {
+		const nativeHistogramConfig = resolveNativeHistogramConfig(config);


super() not being the first line in a constructor is problematic. You're implying side effects that don't exist and leaving a code smell for every subsequent committer to paw through trying to figure out why this is ahead of the super() call.

jdmarshall · 2026-09-11T20:22:08Z

 * @returns {Function} aggregator function
 */
-function AggregatorFactory(aggregatorFn) {
+function AggregatorFactory(aggregatorFn, nativeAggregatorFn) {


I don't see why you need the second parameter.

jdmarshall · 2026-09-11T20:25:08Z

+function AggregatorFactory(aggregatorFn, nativeAggregatorFn) {
 	return metrics => {
 		if (metrics.length === 0) return;
+		const hasNativeHistograms = metrics.some(


And this check runs on every single metric, on every single scrape. This is not when and where to do a sanity check. That should be farther up the chain.

Also why would this happen? You get one histogram with a particular name. Either all of the values will be natives or they won't, right?

jdmarshall · 2026-09-11T20:27:15Z

 		this._collectors = [];
 		this._defaultLabels = {};
 		if (
 			regContentType !== Registry.PROMETHEUS_CONTENT_TYPE &&


This is probably the point to do an array.includes()

jdmarshall · 2026-09-11T20:33:36Z

 			if (defaultLabelNames !== undefined) {
 				for (const labelName of defaultLabelNames) {
 					seriesLabels[labelName] ??= this._defaultLabels[labelName];
+					if (


What is this fixing?

jdmarshall · 2026-09-11T20:34:42Z

 	}

-	async getMetricsAsString(metrics) {
+	async getMetricsAsString(metrics, contentType = this.contentType) {


since encodeMetricFamily doesn't return a string, this is not the way to wire this up.

You're also returning from the middle of a function now.

jdmarshall · 2026-09-11T20:35:55Z

+		if (contentType === Registry.PROMETHEUS_PROTOBUF_CONTENT_TYPE) {
+			const { encodeMetricFamily } = require('./protobuf');
+			return encodeMetricFamily(metric, this._defaultLabels);
+		}


This should be hoisted up to the calling function, which fixes the early exit and the mismatched function name and method signature.

jdmarshall · 2026-09-11T20:38:10Z

+			return encodeMetricFamily(metric, this._defaultLabels);
+		}
+
+		const isOpenMetrics = contentType === Registry.OPENMETRICS_CONTENT_TYPE;


You've got way too many changes in a single commit. I don't see how this one or the one I questioned below are part of native histograms. I know some devs prefer large commits that tie to the ticket, but I've yet to meet one who actually does forensics in git history so I'm pretty sure that's a Chesterton's Fence situation.

If you're going to fix other bugs in a driveby I'd prefer the be done as a separate commit in the same PR. It'll also help because there's already an open PR touching some of the label code and this is going to make a hash of things.

jdmarshall · 2026-09-11T20:41:19Z

@@ -223,9 +250,11 @@ class Registry {
 	setContentType(metricsContentType) {
 		if (


We have two implementations of this.

jdmarshall · 2026-09-11T22:43:10Z

So am I correct in thinking that native histograms are incompatible with the default Prometheus data type? If so then I'm not sure how to keep this compatible with worker.shutdown()

ethanolchik changed the title ~~Add native histograms and Prometheus protobuf exposition~~ feat(metrics): Add native histograms and Prometheus protobuf exposition Sep 10, 2026

jdmarshall reviewed Sep 11, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(metrics): Add native histograms and Prometheus protobuf exposition - #856

feat(metrics): Add native histograms and Prometheus protobuf exposition#856
ethanolchik wants to merge 1 commit into
prometheus:mainfrom
ethanolchik:feat/native-histograms

ethanolchik commented Sep 10, 2026

Uh oh!

jdmarshall Sep 11, 2026 •

edited

Loading

Uh oh!

jdmarshall Sep 11, 2026

Uh oh!

jdmarshall Sep 11, 2026 •

edited

Loading

Uh oh!

jdmarshall Sep 11, 2026

Uh oh!

jdmarshall Sep 11, 2026

Uh oh!

jdmarshall Sep 11, 2026 •

edited

Loading

Uh oh!

jdmarshall Sep 11, 2026 •

edited

Loading

Uh oh!

jdmarshall Sep 11, 2026

Uh oh!

jdmarshall Sep 11, 2026

Uh oh!

jdmarshall commented Sep 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -223,9 +250,11 @@ class Registry {
		setContentType(metricsContentType) {
		if (

Uh oh!

Conversation

ethanolchik commented Sep 10, 2026

Uh oh!

jdmarshall Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

jdmarshall Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

jdmarshall commented Sep 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jdmarshall Sep 11, 2026 •

edited

Loading

jdmarshall Sep 11, 2026 •

edited

Loading

jdmarshall Sep 11, 2026 •

edited

Loading

jdmarshall Sep 11, 2026 •

edited

Loading