stormlog.infer.vllm_metrics

Prometheus text parsing and the vLLM metric catalog.

The parser reads the text exposition that prometheus_client writes for vLLM: # HELP and # TYPE lines name a family, a counter family is named *_total with a separate *_created gauge, and a histogram family exposes _bucket{le=...}, _sum and _count samples. Nothing here imports vLLM, and nothing here turns a scrape into a per-request number: a scrape describes every request the engine served, from every client.

The catalog names what vLLM 0.30.0 exposes and what each series means. A series the catalog does not name is kept under its native name, never dropped; a name vLLM has retired is recognised and mapped to its successor.

Functions

bucket_boundary(le)	The numeric upper bound of a bucket; +Inf is infinity.
compact_scrape(families)	Fold parsed families into the compact per-scrape form.
created_family_for(name[, kind])	The *_created gauge that marks when a counter or histogram was made.
decode_number(value)	The inverse of encode_number(); other strings are an error.
discover(scrape)	Compare a scrape with the catalog without discarding anything.
encode_number(value)	A sample value as strict JSON: NaN and infinities become strings.
family_group(name)	The catalog group of a series; optional prefixes name their subsystem.
parse_prometheus_text(text, *[, max_series])	Parse a text scrape into families keyed by their # TYPE name.
process_start_ns(scrape)	The exporting process's start time, or None when a scrape has no single one.
resolve_name(name)	Return the current catalog name and the retired alias it replaced, if any.

Classes

CatalogEntry(name, kind, field, group, unit, ...)	What one vLLM series means and how Stormlog refers to it.
CompactScrape(families, label_sets, values)	One scrape with every series kept, label sets shared across series.
Discovery(present, absent, optional_absent, ...)	What one scrape exposes, measured against the catalog.
HistogramValue(buckets, sum, count)	Cumulative bucket counts under their native le boundaries.
MetricFamily(name, kind, help[, samples])	A # TYPE family and the samples that belong to it.
Sample(name, labels, value)	One exposed series: its full sample name, sorted labels and value.

Exceptions

ScrapeTooLarge

A line over MAX_LINE_CHARS, or more series or families than allowed.

exception stormlog.infer.vllm_metrics.ScrapeTooLarge

Bases: ValueError

A line over MAX_LINE_CHARS, or more series or families than allowed.

class stormlog.infer.vllm_metrics.Sample(name, labels, value)

Bases: object

One exposed series: its full sample name, sorted labels and value.

Parameters:

• name (str)

• labels (tuple[tuple[str, str], ...])

• value (float)

name: str

labels: tuple[tuple[str, str], ...]

value: float

class stormlog.infer.vllm_metrics.MetricFamily(name, kind, help, samples=())

Bases: object

A # TYPE family and the samples that belong to it.

Parameters:

• name (str)

• kind (str)

• help (str)

• samples (tuple[Sample, ...])

name: str

kind: str

help: str

samples: tuple[Sample, ...] = ()

stormlog.infer.vllm_metrics.parse_prometheus_text(text, *, max_series=None)

Parse a text scrape into families keyed by their # TYPE name.

A sample without a preceding # TYPE line belongs to an untyped family of its own name. A line that is neither a comment nor a sample raises ValueError naming the line, so a truncated or HTML response never passes as an empty scrape.

What parsing holds is bounded whatever the text: lines are read one at a time, a line over MAX_LINE_CHARS raises ScrapeTooLarge before any regex sees it, and so does a sample or family past max_series.

Parameters:

• text (str)

• max_series (int | None)

Return type:

dict[str, MetricFamily]

class stormlog.infer.vllm_metrics.HistogramValue(buckets, sum, count)

Bases: object

Cumulative bucket counts under their native le boundaries.

sum or count is None when the exposition lacked that sample: it is kept missing, never invented as zero, so nothing differences it.

Parameters:

• buckets (tuple[tuple[str, float], ...])

• sum (float | None)

• count (float | None)

buckets: tuple[tuple[str, float], ...]

sum: float | None

count: float | None

to_record()

Return type:

dict[str, Any]

classmethod from_record(record)

Parameters:

record (dict[str, Any])

Return type:

HistogramValue

property boundaries: tuple[float, ...]

stormlog.infer.vllm_metrics.encode_number(value)

A sample value as strict JSON: NaN and infinities become strings.

Parameters:

value (float)

Return type:

float | str

stormlog.infer.vllm_metrics.decode_number(value)

The inverse of encode_number(); other strings are an error.

Parameters:

value (Any)

Return type:

float

stormlog.infer.vllm_metrics.bucket_boundary(le)

The numeric upper bound of a bucket; +Inf is infinity.

Parameters:

le (str)

Return type:

float

class stormlog.infer.vllm_metrics.CompactScrape(families, label_sets, values, helps=<factory>)

Bases: object

One scrape with every series kept, label sets shared across series.

values maps a family name to {label set id: value}; a value is a float for gauges, counters and untyped series, and a HistogramValue for histograms. Summaries keep their quantiles as a histogram-like value whose bucket boundaries are quantiles.

Parameters:

• families (dict[str, str])

• label_sets (dict[str, dict[str, str]])

• values (dict[str, dict[str, float | HistogramValue]])

• helps (dict[str, str])

families: dict[str, str]

label_sets: dict[str, dict[str, str]]

values: dict[str, dict[str, float | HistogramValue]]

helps: dict[str, str]

to_record()

Return type:

dict[str, Any]

classmethod from_record(record)

Parameters:

record (dict[str, Any])

Return type:

CompactScrape

series(name)

Values of one family by label set id; empty when absent.

Parameters:

name (str)

Return type:

dict[str, float | HistogramValue]

labels(set_id)

Parameters:

set_id (str)

Return type:

dict[str, str]

label_values(label)

Every distinct value of one label, sorted.

Parameters:

label (str)

Return type:

tuple[str, …]

scalar(name, set_id)

Parameters:

• name (str)

• set_id (str)

Return type:

float | None

stormlog.infer.vllm_metrics.compact_scrape(families)

Fold parsed families into the compact per-scrape form.

Parameters:

families (dict[str, MetricFamily])

Return type:

CompactScrape

class stormlog.infer.vllm_metrics.CatalogEntry(name, kind, field, group, unit, meaning, labels=(), requires=None, provenance='observed')

Bases: object

What one vLLM series means and how Stormlog refers to it.

Parameters:

• name (str)

• kind (str)

• field (str)

• group (str)

• unit (str | None)

• meaning (str)

• labels (tuple[str, ...])

• requires (str | None)

• provenance (str)

name: str

kind: str

field: str

group: str

unit: str | None

meaning: str

labels: tuple[str, ...] = ()

requires: str | None = None

provenance: str = 'observed'

stormlog.infer.vllm_metrics.created_family_for(name, kind='counter')

The *_created gauge that marks when a counter or histogram was made.

prometheus_client names a counter’s stamp without the _total suffix (vllm:prompt_tokens_created) but a histogram’s with its full name, so vllm:iteration_tokens_total, a histogram despite the suffix, is stamped as vllm:iteration_tokens_total_created.

Parameters:

• name (str)

• kind (str)

Return type:

str | None

stormlog.infer.vllm_metrics.resolve_name(name)

Return the current catalog name and the retired alias it replaced, if any.

Parameters:

name (str)

Return type:

tuple[str, str | None]

class stormlog.infer.vllm_metrics.Discovery(present, absent, optional_absent, deprecated_present, removed_present, unknown, engines, model_names, process_start_ns, optional_present=())

Bases: object

What one scrape exposes, measured against the catalog.

Parameters:

• present (tuple[str, ...])

• absent (tuple[str, ...])

• optional_absent (tuple[str, ...])

• deprecated_present (tuple[str, ...])

• removed_present (tuple[str, ...])

• unknown (tuple[str, ...])

• engines (tuple[str, ...])

• model_names (tuple[str, ...])

• process_start_ns (int | None)

• optional_present (tuple[str, ...])

present: tuple[str, ...]

absent: tuple[str, ...]

optional_absent: tuple[str, ...]

deprecated_present: tuple[str, ...]

removed_present: tuple[str, ...]

unknown: tuple[str, ...]

engines: tuple[str, ...]

model_names: tuple[str, ...]

process_start_ns: int | None

optional_present: tuple[str, ...] = ()

to_record()

Return type:

dict[str, Any]

stormlog.infer.vllm_metrics.discover(scrape)

Compare a scrape with the catalog without discarding anything.

Parameters:

scrape (CompactScrape)

Return type:

Discovery

stormlog.infer.vllm_metrics.process_start_ns(scrape)

The exporting process’s start time, or None when a scrape has no single one.

Parameters:

scrape (CompactScrape)

Return type:

int | None

stormlog.infer.vllm_metrics.family_group(name)

The catalog group of a series; optional prefixes name their subsystem.

Parameters:

name (str)

Return type:

str