01 · Problem
What is it for?
Names, escaped labels, metadata and special numeric values need a grammar rather than whitespace splitting.
02 · Mental model
How should you think about it?
Metadata identifies a family; each sample adds a name, labels, value and optional timestamp.
Parses metric families, metadata, escaped labels and complete numeric values. This parser targets Prometheus text exposition, not all OpenMetrics extensions.
03 · Control flow
What happens in which order?
- Read HELP and TYPE directives by metric name.
- Scan a sample name and quoted labels.
- Validate the complete numeric token.
- Associate samples with the appropriate family.
- Return structured families.
04 · Building blocks
The important contracts
parsePrometheusMetrics(text)Read metadata and samples into separate families.parseSample / parseLabelsValidate numeric tokens and escaped quoted labels.05 · Build it yourself
Implement a small core
Start with this small independent implementation, then use the steps below to make its contract explicit.
- Read HELP and TYPE directives by metric name.
- Scan a sample name and quoted labels.
- Validate the complete numeric token.
- Associate samples with the appropriate family.
- Return structured families.
type Sample = { name: string; value: number };
function parseSimpleSample(line: string): Sample {
const split = line.lastIndexOf(" ");
if (split < 1) throw new Error("Incomplete sample");
const head = line.slice(0, split).trim();
const raw = line.slice(split + 1).trim();
const value = Number(raw);
if (Number.isNaN(value)) throw new Error("Invalid value");
const brace = head.indexOf("{");
const name = head.slice(0, brace < 0 ? head.length : brace);
if (!name) throw new Error("Missing metric name");
return { name, value };
}06 · Verify
What should you test?
- Separate two metric families correctly.
- Preserve commas, equals signs and escaped quotes inside labels.
- Accept NaN and infinities but reject numeric suffix garbage.
Try it yourself
Turn the first verification claim into a failing test, implement the smallest fix, then add a boundary case.
Separate two metric families correctly.
Compare your approach
Your check should fail when the stated invariant is deliberately broken, and pass again after the fix. Keep setup deterministic and assert an observable result.
07 · Limits
Trade-offs and failure modes
- Prometheus text and OpenMetrics differ.
- Histogram suffixes belong to their base family.
- Reject unsupported syntax explicitly.
This parser targets Prometheus text exposition, not all OpenMetrics extensions.
08 · Keep exploring
Source code and related ideas
yarn tsx packages/prom-metrics-parser/examples/basic.ts