Metric

A metric a library module declares once and records through MetricsCollector.increment, MetricsCollector.observe and MetricsCollector.set: its name, what it measures, and the names of its labels, in the order their values are passed. It is how a module above core (the agent runtime, say) reports metrics core knows nothing about, while every MetricsCollector backend exports them the same way.

The name is lower-case words separated by dots, such as llm4s.agent.runs.started, the Micrometer convention. A Prometheus backend turns the dots into underscores and adds the unit suffix: a counter is exposed as llm4s_agent_runs_started_total, a timer as <name>_seconds, a gauge under its name. So no name ends in total, nor a timer's in seconds: the backend adds them. A gauge names its own unit, such as llm4s.agent.queue.oldest.seconds.

Label values must come from a bounded set - an outcome, a status, an agent id fixed by the code - and carry no content. Never a thread, run, request or tenant id, a prompt or a message: each distinct value is a series kept for the life of the process. A backend caps the distinct values of each label (see MetricsCollector.MaxLabelValues) and records further values as other.

Built by Metric.counter, Metric.timer and Metric.gauge, which throw IllegalArgumentException for an invalid name, label or bucket: a metric is a constant of the code that declares it, so a bad one fails where it is declared, at class initialisation, rather than at its first recording.