Module metrics 

FFI-safe metric types and the recorder helper plugins use to emit Prometheus metrics through the hub.

Design

Plugins don’t talk to a Prometheus exporter directly — the hub owns the /metrics endpoint and the metrics crate registry. Instead the hub hands each plugin a RecordMetricFn callback at init time, and the plugin invokes it whenever it wants to emit a counter increment, gauge set, or histogram observation. The callback routes into the hub’s existing metrics::{counter, gauge, histogram} macros, prefixing the metric name with plugin_<plugin>_ so plugin metrics are namespaced (matches the hub’s own spoa_* and spoa_hub_* prefix discipline).

Why push, not pull

A pull-based design (hub asks each plugin “what are your current metric values?” on every Prometheus scrape) would require plugins to re-aggregate histograms into Prometheus bucket counts on each scrape and serialise them across the FFI boundary every time. The push design lets each event go straight into the hub’s existing recorder at the moment it happens — same code path the hub’s own metrics use, with native histogram observation support and no per-scrape FFI traffic.

Lifetime contract

The recorder callback and its ctx pointer remain valid from the moment the hub calls set_metric_recorder on a plugin until that plugin’s destroy returns. Plugins MUST NOT call the recorder after returning from destroy. The hub MUST NOT free the ctx until it has called destroy on every plugin that received it.

Structs

MetricRecorder

Ergonomic plugin-side helper that wraps the FFI recorder.

Enums

MetricKind

Kind of metric being recorded. The hub dispatches each call into the matching metrics crate primitive (counter! / gauge! / histogram!). #[repr(u8)] pins the discriminant so plugins built against any version of this crate agree on the wire encoding.

Type Aliases

MetricLabel

One label pair (key, value) on a metric sample. Borrowed from the caller; the recorder copies into the hub’s registry before returning.

RecordMetricFn

FFI signature the hub provides to each plugin via PluginVTable::set_metric_recorder.