MetricMapping Custom Resource
This document applies to the Modelplane main branch and not to the latest release v0.5.
How one component’s metrics become part of the modelplane_* surface. Modelplane renders every MetricMapping into each inference cluster’s collector, so a mapping is written once on the control plane and reaches the whole fleet.
A mapping naming a component Modelplane already provides renames for is additive: its renames run after the built-in ones, on whatever those left behind. A metric a built-in already renamed no longer answers to the name it was emitted under, so a second mapping selecting on that name matches nothing and the built-in stands. Select on the modelplane_ name instead to rename one of Modelplane’s own.
Concept guide: Monitor the Fleet →
#Metadata
#Spec
How one component’s metrics become part of the modelplane_* surface. Modelplane renders every MetricMapping into each inference cluster’s collector, so a mapping is written once on the control plane and reaches the whole fleet.
A mapping naming a component Modelplane already provides renames for is additive: its renames run after the built-in ones, on whatever those left behind. A metric a built-in already renamed no longer answers to the name it was emitted under, so a second mapping selecting on that name matches nothing and the built-in stands. Select on the modelplane_ name instead to rename one of Modelplane’s own.
The metric’s name as the component exposes it, matched exactly wherever it appears in the fleet.
A histogram is named by its base name, without the _count, _sum or _bucket a Prometheus query would use: the collector holds it as one metric, and part is what reaches into it.
What the component measures this in, when that isn’t the unit the name claims. Modelplane converts to the base unit: millijoules and milliseconds are divided by a thousand, nanoseconds by a billion, percent by a hundred, and mebibytes multiplied out to bytes. A histogram is converted whole - its sum, its bounds and its bucket boundaries - so its quantiles come out in the target unit too. Percent is for a component that counts a saturation from nought to a hundred where the name says a ratio. Check rather than assume: vLLM publishes kv_cache_usage_perc and the value is a fraction, so a name is no guide.
A label the component already emits. Modelplane copies its value into this label and removes the original.
Naming the label itself keeps it: that is how values rewrites what a component writes without renaming the label.
The label to set.
A fixed value, the same on every series this mapping produces. This is what tells two folded metrics apart.
What each of that label’s values becomes, for putting an engine’s own vocabulary into Modelplane’s. A value with no entry here is left as the component wrote it.
Take a part of a histogram as a counter of its own, rather than the histogram itself. Count is how many observations it holds, which is a request count where the histogram measures request duration. Sum is their total.
The extraction leaves the histogram alone, but the collector exports only what a mapping renames, so the histogram itself is dropped unless another mapping gives it a modelplane_ name of its own. Write that second mapping to keep both.
The name to export the metric under. Only modelplane_* metrics leave a cluster, so a metric no mapping renames never leaves its cluster.
Name it in base units - seconds, bytes, joules, a ratio from nought to one - because that is what fromUnit converts to.