Skip to content

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

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

feat(metrics): add metric validation + UTF-8 support#238
ethanolchik wants to merge 25 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 label names only whne they require UTF-8 syntax; legacy-compatible label names remain unquoted.
  • 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 2 times, most recently from ff0cd51 to 7e00086 Compare July 24, 2026 14:43
@ethanolchik
ethanolchik force-pushed the validation-and-utf8 branch from 7e00086 to c5b338a Compare July 27, 2026 16:54
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