Skip to content

feat(metrics): add metric validation + UTF-8 support#238

Draft
ethanolchik wants to merge 20 commits into
cloudflare:mainfrom
ethanolchik:validation-and-utf8
Draft

feat(metrics): add metric validation + UTF-8 support#238
ethanolchik wants to merge 20 commits into
cloudflare:mainfrom
ethanolchik:validation-and-utf8

Conversation

@ethanolchik

@ethanolchik ethanolchik commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

What Changed

Introduces shared validation used during collection and by both encoders.

Names are valid when they are non-empty UTF-8 strings without NUL (\0) bytes. Names containing spaces, punctuation, newlines, or non-ASCII characters remain valid and are escaped appropriately for text output.

Validation failures are isolated as narrowly as possible:

  • An invalid family name drops that family.
  • An invalid, duplicate, or reserved label drops only its metric row.
  • An invalid or duplicate exemplar label drops only the exemplar.
    • This branch validates exemplars already present in MetricFamily; exemplar-producing metric types are introduced separately.
  • Other families and rows continue to be collected and encoded.
  • Every dropped value produces a non-fatal diagnostic with collection or encoding context.

Histogram and gauge-histogram rows reserve le, while summary rows reserve quantile, according to the canonical metric model.

Service Labels

Service-label insertion now handles existing labels safely:

  • A row already containing the configured label and value is unchanged.
  • A row containing the same label with a different value is dropped.
  • A missing service label is prepended as before.
  • An invalid configured service-label name prevents collection instead of producing malformed output.

OpenMetrics Text

The text encoder now:

  • Quotes all label names.
  • Uses quoted OpenMetrics syntax for metric names outside the legacy grammar.
  • Escapes metric and label names safely.
  • Appends histogram suffixes inside quoted metric names.
  • Exports OPENMETRICS_CONTENT_TYPE with escaping=allow-utf-8.
    Legacy-compatible metric names remain unquoted.

Protobuf

Protobuf output preserves valid UTF-8 names exactly. The protobuf encoder applies the same defensive validation when called directly, so bypassing collection does not bypass validation.

@ethanolchik
ethanolchik force-pushed the validation-and-utf8 branch from 6cd35d0 to ff0cd51 Compare July 24, 2026 12:07
… names

Legacy metric and label names must match Prometheus' name grammars. Names outside these grammars cause Prometheus to reject the scrape, and the grammars exclude non-ASCII characters.

Foundations now quotes label names and uses OpenMetrics' quoted metric-name syntax when required. This allows UTF-8 and other nonstandard names without affecting legacy compatibility.
@ethanolchik
ethanolchik force-pushed the validation-and-utf8 branch from ff0cd51 to 7e00086 Compare July 24, 2026 14:43
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.

1 participant