Skip to content

feat(metrics): add protobuf and OpenMetrics text encoders and collection - #237

Merged
fisherdarling merged 7 commits into
cloudflare:mainfrom
ethanolchik:encoders-and-collect
Jul 30, 2026
Merged

feat(metrics): add protobuf and OpenMetrics text encoders and collection#237
fisherdarling merged 7 commits into
cloudflare:mainfrom
ethanolchik:encoders-and-collect

Conversation

@ethanolchik

@ethanolchik ethanolchik commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Overview

This PR completes the path from registered metrics to Prometheus-compatible wire output:

  1. Collect registered metrics into the canonical protobuf MetricFamily model.
  2. Encode those families as length-delimited Prometheus protobuf or OpenMetrics text.

The public API now exposes collect, CollectionOptions, ServiceNameFormat, encode_to_protobuf, and encode_to_text.

Collection

collect iterates over the global registry and encodes each registered metric into one or more MetricFamily values.

CollectionOptions controls whether optional metrics are included and how a service name is represented:

  • MetricPrefix prefixes metric family names, except metrics registered as unprefixed.
  • LabelWithName adds the service name as a label to every row.

The resulting Vec<MetricFamily> provides a common boundary between metric implementations and wire encoders.

Encoding

encode_to_protobuf serialises metric families as concatenated, length-delimited Prometheus protobuf messages. This preserves fields that OpenMetrics text cannot fully represent, including native histogram data.

encode_to_text supports:

  • Counters
  • Gauges
  • GaugeHistograms
  • Summaries
  • Untyped metrics
  • Classic histograms

Info metrics have no dedicated metric type; they are ordinary gauge families valued 1 that carry their fields as labels. Tests pin this representation in both formats (the family name is unchanged (for example, build_info), the protobuf type is gauge, and text emits # TYPE build_info gauge) so that the info-metric layer added in a later PR reproduces the legacy wire output exactly. This PR adds no way to define or report an info metric.

The text encoder emits # HELP, # TYPE, and # UNIT metadata and terminates output with # EOF. Empty # HELP lines are omitted from output.

Histogram encoding:

  • Maps the terminal f64::MAX bucket to +Inf.
  • Adds a terminal +Inf bucket when missing.
  • Preserves classic histogram bucket exemplars.
  • Skips native-only histogram rows.
  • Skips histogram rows with positive floating-point counts.

The encoder also handles metric and exemplar timestamps, escapes help text and label values, and emits NaN, +Inf, and -Inf using OpenMetrics syntax.

Summary and GaugeHistogram families are fully supported. Protobuf passes them through unchanged. In text, summaries emit their quantile rows plus _sum and _count; gauge histograms emit _bucket rows plus _gsum and _gcount.

For text output, families without a non-empty name or recognised type, and rows missing data for their declared type, are skipped and reported through the non-fatal collection error hook.

@ethanolchik
ethanolchik force-pushed the encoders-and-collect branch from 8e54c49 to 1a7e8f5 Compare July 24, 2026 11:51
@ethanolchik
ethanolchik force-pushed the encoders-and-collect branch 2 times, most recently from b420c26 to 6a04141 Compare July 24, 2026 14:43
@ethanolchik ethanolchik changed the title feat(metrics): add protobuf and OpenMetrics text encoders, collection, and info metrics. feat(metrics): add protobuf and OpenMetrics text encoders and collection Jul 27, 2026
@ethanolchik
ethanolchik force-pushed the encoders-and-collect branch from 6a04141 to 1746521 Compare July 27, 2026 16:54
@ethanolchik
ethanolchik marked this pull request as ready for review July 28, 2026 15:13
@ethanolchik
ethanolchik force-pushed the encoders-and-collect branch from 8e37dcf to 2622a74 Compare July 30, 2026 10:49
@fisherdarling
fisherdarling merged commit 4c3ba56 into cloudflare:main Jul 30, 2026
19 checks passed
@ethanolchik
ethanolchik deleted the encoders-and-collect branch July 30, 2026 11:19
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