Missing EnumMetricFamily for custom collector

[andreynovikov]

I want to expose Enum in my custom collector, but there is no implementation for EnumMetricFamily. Is it on purpose? How can I substitute it?

[chrikrah]

@andreynovikov this is a year old now, so for whoever lands here next: StateSetMetricFamily is the custom-collector form of Enum. Enum declares itself as a stateset metric (metrics.py:759), and the family class emits the same samples, one 0/1 series per state with the state name as a label.

from prometheus_client import CollectorRegistry, Enum, generate_latest
from prometheus_client.core import StateSetMetricFamily

states = ["starting", "running", "stopped"]

class TaskCollector:
    def collect(self):
        m = StateSetMetricFamily("task_state", "Task state", labels=["task"])
        m.add_metric(["t1"], {s: s == "running" for s in states})
        yield m

custom = CollectorRegistry()
custom.register(TaskCollector())
print(generate_latest(custom).decode())

direct = CollectorRegistry()
Enum("task_state", "Task state", ["task"], states=states, registry=direct).labels("t1").state("running")
lines = lambda r: sorted(generate_latest(r).splitlines())
print("same lines as Enum:", lines(custom) == lines(direct))

$ python enum_answer.py     # client_python 9cd073c, Python 3.12.3
# HELP task_state Task state
# TYPE task_state gauge
task_state{task="t1",task_state="running"} 1.0
task_state{task="t1",task_state="starting"} 0.0
task_state{task="t1",task_state="stopped"} 0.0

same lines as Enum: True

The lines only match after sorting: add_metric sorts the states by name, while Enum keeps the order you declared. The text format shows gauge; the OpenMetrics encoder shows stateset.

The name is easy to miss because docs/content/collector/custom.md covers the Gauge, Counter, Summary, Histogram and Info families and has no section for this one, nor for GaugeHistogramMetricFamily or UnknownMetricFamily.

@csmarchbanks would a docs pull request adding sections for those three to custom.md be welcome?