Crate nmbrs_metrics

Expand description

§nmbrs-metrics

Contract & axioms: SRD 39.

Metrics collection and reporting for nmbrs. The design centers on a component tree — a hierarchical, label-keyed structure where every node owns its own instruments, controls, and child components. Workload state, phase progress, latency histograms, and dynamic-control values are all reified as components and their attached instruments, queryable via selector::Selector or directly via parent / child traversal.

§Pieces

Components (component::Component) hold dimensional labels (session=…, phase=…, activity=…), per-component props, an instrument set, and a control registry. Each component’s effective labels are the union of its own labels and its parent chain.
Instruments (instruments) are counters, gauges, histograms, timers — owned by a component and accessed by name. Histograms are HDR-backed; reads return delta windows so downstream reporters get what changed since last read, not cumulative state.
Snapshots (snapshot::MetricSet) are OpenMetrics-shaped captures of one moment in time across the tree. The cadence_reporter::CadenceReporter coalesces snapshots into declared windows (1s, 10s, 30s, 1m, 5m, …) and fans them out to async subscribers (SQLite, VictoriaMetrics push, TUI).
Controls (controls) live next to instruments — same tree, same label addressing — but carry mutable typed values that Polydat Kernels read at cycle time and the runtime applies via ControlAppliers. See SRD 23 for the full surface.
MetricsQuery (metrics_query::MetricsQuery) is the read-side handle that consumers (TUI, web, summary reports) use to pull cadence-window snapshots without touching the shared store directly.

§Quick tour

Build a root component, then walk it:

use std::collections::HashMap;
use nmbrs_metrics::component::{self, Component};
use nmbrs_metrics::labels::Labels;
use nmbrs_metrics::selector::Selector;

let root = Component::root(
    Labels::of("session", "demo"),
    HashMap::new(),
);

// Effective labels include the chain back to the root.
let guard = root.read().unwrap();
assert_eq!(guard.effective_labels().get("session"), Some("demo"));
drop(guard);

// Empty selector matches the root only on a fresh tree.
let hits = component::find(&root, &Selector::new());
assert_eq!(hits.len(), 1);

§Design briefs

See the SRD for the full rationale:

SRD 19 — component tree
SRD 23 — dynamic controls
SRD 24 — selector lookup semantics
SRD 40 / 42 — metrics capture, cadence reporter, subscription dispatch

Modules§

cadence: Cadence planning: user-declared cadences + auto-intermediate tree synthesis.
cadence_reporter: Cadence reporter — single writer of windowed snapshots (SRD-42 §“Wire-Up → Cadence reporter”).
cells: Dimensional cells materialised from data.
component: Runtime component tree for metrics ownership and dimensional labels.
controls: Dynamic controls — see SRD 23.
diag: Diagnostic logging sink for nmbrs-metrics.
instruments: Primary metric instruments.
labels: Dimensional metric labels.
metrics_query: Unified metrics read API (SRD-42 §“MetricsQuery”).
polydat_nodes: Polydat-side metric-reading node registration.
queryapi: The metrics query API — the data-access service boundary (SRD-86 §“The metric-reader surface”).
reporters: Metric reporters.
scheduler: Metrics snapshot scheduler with hierarchical frame coalescing.
selector: Component lookup by label predicate — see SRD 24.
snapshot: OpenMetrics-aligned snapshot data model (SRD-42 §“Snapshot data model”). Mirrors the OpenMetrics specification 1:1 so external consumers (Prometheus scrape, OTel translation, third-party dashboards) get a near-trivial projection.
summaries: Summaries — retained, transforming views of instrument data.
thread_pools: SRD-102 — Named physical thread pools.
validation: OpenMetrics 1.0 validation helpers.

Macros§

selector: Compile-time-expanded Selector builder. Equivalent to a sequence of .eq(key, value) calls: