Metric Types and Data Model

## What a target actually serves A Prometheus target exposes a plain-text document over HTTP. There is no envelope, no JSON, no schema: the body is a sequence of lines, and the whole Prometheus data model is visible in them. A **sample line** has three or four parts: ``` metric_name{label="value",other="value"} 12.7 1757116800000 ``` - **metric name** — the identity of the metric family. - **label set** — zero or more `name="value"` pairs inside braces, comma separated, values double-quoted and escaped. Omit the braces entirely when there are no labels. - **value** — parsed as a `float64`. `NaN`, `+Inf` and `-Inf` are legal, and an integer is simply a float that happens to be whole. - **timestamp** — optional, an `int64` count of milliseconds since the Unix epoch. Almost every target omits it, and that is the right default: the server then stamps the sample with the scrape time, so every sample from one scrape shares one timestamp. The detail that surprises people is that the metric name is itself a label. A series is identified by its complete label set, and the name lives in the reserved label `__name__`, so `seedorder_http_requests_total{route="/v1/checkout"}` and `{__name__="seedorder_http_requests_total",route="/v1/checkout"}` name the same series. ## The two comment lines Lines beginning with `#` are comments. Two of them are special, and both belong to a **metric family** (all the series sharing one metric name), not to an individual line: - `# HELP <name> <free-form text>` — one human-readable description of the family. - `# TYPE <name> <type>` — declares the family as `counter`, `gauge`, `histogram`, `summary` or `untyped`. By convention a family's `# HELP` and `# TYPE` lines precede its samples and all of a family's samples are grouped together. Any other `#` line is an ordinary comment and is ignored. ## What the server keeps and what it discards | Element of the exposition | Where it ends up | |---|---| | metric name | stored, as the `__name__` label of the series | | labels | stored, part of the series identity | | value | stored, as a `float64` | | explicit timestamp | used if present, otherwise the scrape time is used | | `# HELP` text | kept as per-target metadata, never attached to a sample | | `# TYPE` declaration | kept as per-target metadata, never attached to a sample | | any other comment line | discarded | The metadata rows are the ones that matter in an interview. Prometheus parses `# HELP` and `# TYPE`, keeps the most recent value **per metric, per target**, exposes it over the server's metric-metadata HTTP API and uses it in the expression browser. It is never a sample. Four consequences follow: 1. **There is no history.** Only the latest description and type are available; you cannot ask what a metric's help text said last week. 2. **PromQL cannot select on it.** There is no way to write "every counter" — the declared type is not part of any series' identity. 3. **The declaration is advisory.** Declaring `counter` does not make the server reject a value that goes down, and declaring `gauge` does not stop anything from treating the series as cumulative. Storage is identical either way: a series plus timestamp/value pairs. 4. **Nothing enforces agreement.** Two targets in the same job may declare the same metric name with different types or different help text; the metadata surface just reports what each target said. So a wrong `# TYPE` is a documentation defect. It misleads humans, autocompletion and linters, and it produces silently wrong dashboards when somebody trusts it — but it is never an ingestion error. ## OpenMetrics, the negotiated variant Prometheus can negotiate a second text format, OpenMetrics, through the `Accept` header. It is deliberately close to the classic format, with a handful of differences worth recognising: it adds a `# UNIT` metadata line, it names the unspecified type `unknown` rather than `untyped`, it requires the document to end with a `# EOF` line, and it can carry an exemplar on a sample line. Everything above still applies — `# UNIT` is metadata, not data. ## Why the thinness matters in practice Because the format is this thin, most integration problems reduce to reading it. A seed-catalogue ordering service in a newly brought-up region that "exports nothing" is diagnosed by fetching the text and looking: an empty body, a body with `# HELP` and `# TYPE` lines but no samples, and a body whose label values are unescaped are three completely different bugs that look identical from a dashboard. The flip side of a format that is trivial to generate is that nothing validates your output. A line with an unquoted label value or a stray second numeric field makes the parse fail, and a failed parse fails the whole scrape — not just that line — so none of that scrape's samples land. That is why exporters that build the text by hand are worth a test that parses their own output before shipping.