Struct MetricRecorder 

pub struct MetricRecorder { /* private fields */ }

Ergonomic plugin-side helper that wraps the FFI recorder.

Plugins embed a MetricRecorder in their state, the define_plugin! macro wires it via the set_metric_recorder vtable entry, and plugin code calls the typed counter / gauge / histogram methods from anywhere with &self.

pub struct MyPlugin {
    metrics: MetricRecorder,
    // ...other state
}

impl MyPlugin {
    fn process(&self, msg: &SpoeMessage) -> Result<ProcessingResult, _> {
        self.metrics.counter("dispatches_total", &[("kind", "ok")], 1);
        self.metrics.histogram("latency_seconds", &[], 0.012);
        // ...
    }
}

When the recorder is not yet installed (between create and the hub’s set_metric_recorder call) or the host is running a v1 hub that never installs one, the methods are inexpensive no-ops — a single uncontended read-lock acquire that observes None.

Why RwLock<Option<…>> and not OnceLock<…>

Plugins are typically declared as pub(crate) static METRICS: MetricRecorder = MetricRecorder::new(); — a process-wide singleton living in the .so’s BSS. The hub keeps the .so mapped across plugin reloads via libloading::Library refcounting, so the static survives every reload and accumulates state across plugin instances. With an internal OnceLock, install() was silently no-op on the second-and-later plugin loads: the NEW plugin’s hub ctx pointer never replaced the OLD one. When the hub then dropped the OLD plugin’s Box<MetricCtx> (after the OLD plugin’s last in-flight process() call retired), the stale OLD pointer in MetricRecorder became a use-after-free; the next counter() / gauge() / histogram() from any plugin instance — old or new — dereferenced freed memory and segfaulted the hub process. The haptic conformance suite reproduces this on every conformance shard run because its reconciliationDebounceInterval=10ms triggers rapid back-to-back HAProxy general-storage writes, each of which the hub’s file-watcher turns into a plugin reload.

RwLock lets install() actually REPLACE the inner on every call, which is what plugin reload requires. Read paths (emit) take the read lock for the duration of the recorder callback, holding the pointer valid against a racing install() from a concurrent reload. The hub’s lifetime contract — “ctx is valid until the plugin instance that received it is destroyed” — combined with the hub’s drop ordering (Plugin::drop calls destroy() BEFORE dropping Box<MetricCtx>) means a NEW install always lands BEFORE the corresponding OLD Box is freed, so once emit reads NEW inner under its read lock, the ctx it observes is the NEW one and stays valid for the call.

Implementations

impl MetricRecorder

pub const fn new() -> Self

Construct an uninitialised recorder. Plugins embed this in their state; the define_plugin! macro fills it in when the hub calls set_metric_recorder.

pub fn counter(&self, name: &str, labels: &[(&str, &str)], increment: u64)

Increment a counter. increment is typically 1. Names are hub-namespaced — emitting "dispatches_total" from the mirror plugin lands as plugin_mirror_dispatches_total in Prometheus.

pub fn gauge(&self, name: &str, labels: &[(&str, &str)], value: f64)

Set a gauge. Replaces the previous value for this (name, labels) tuple in the registry.

pub fn histogram(&self, name: &str, labels: &[(&str, &str)], value: f64)

Record a histogram observation. Bucket boundaries are governed by the hub’s Prometheus exporter config; plugins that need custom buckets coordinate with the hub at deploy time.

Trait Implementations

impl Debug for MetricRecorder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MetricRecorder

fn default() -> Self

Returns the “default value” for a type.