Struct MetricsQuery 

pub struct MetricsQuery { /* private fields */ }

The unified metrics read interface. Constructed once at session start with references to the cadence reporter (for closed windows + cascade peeks) and the component tree root (for the now mode’s live instrument walk).

Implementations

impl MetricsQuery

pub fn new( reporter: Arc<CadenceReporter>, component_root: Arc<RwLock<Component>>, ) -> Self

pub fn reporter(&self) -> &Arc<CadenceReporter>

Reference to the cadence reporter — exposed so consumers that need to enumerate declared cadences (e.g., per-cadence columns) can ask it directly.

pub fn running_phase_count(&self) -> usize

Count of phases currently in Running state anywhere in the session’s component tree. A pure structural query — no metric data involved. Used by display code that needs to decide “live vs waiting vs done” without re-implementing that logic over its own state mirror.

pub fn now(&self, selection: &Selection) -> MetricSet

Recent snapshot at the smallest declared cadence, filtered by selection.

Reads Self::cadence_window at the smallest declared cadence (1 s for default configurations) — the last fully- closed window of that cadence. Does NOT pass through to the live instruments: counter values, gauge values, and histogram reservoirs all come from the cadence-reporter store, which the scheduler populates via its per-tick coalesce.

Why not a live-instrument peek? Counters are absolute atomics (peek is free), but histogram peeks return “samples accumulated since the scheduler’s last drain” — a partial, drifting sub-interval window. The 1 s cadence window is a stable, sample-weighted view that matches what every other reader (summary, SQLite, cadence subscribers) sees for the same time slice.

Returns an empty MetricSet before the first window of the smallest declared cadence closes (i.e., during the first 1 s of a run). Callers that need true sub-second live data for a specific Timer should use crate::instruments::timer::Timer::peek_live_window.

pub fn resolve(&self, selection: Selection) -> MetricHandle

Build a MetricHandle that caches the (selection, cadence) pair for repeated cheap reads. The handle reads the smallest declared cadence’s last closed window on every read_now — no component-tree walk, no live-instrument access.

Callers that want a specific cadence (not the smallest) can use Self::resolve_at.

pub fn resolve_at( &self, selection: Selection, cadence: Duration, ) -> MetricHandle

Same as Self::resolve but pins the handle to a specific cadence — use for per-cadence columns in summary reports or for explicit longer-horizon readers.

pub fn cadence_window( &self, cadence: Duration, selection: &Selection, ) -> MetricSet

Latest fully-closed snapshot for the named cadence, filtered by selection. Returns an empty snapshot when no closed window has been published yet (early in a run).

Walks every component tracked by the cadence reporter, merging matching metrics into one result. Identity follows OpenMetrics §4.5.1 — same (family.name, label_set) combines.

pub fn increase_over(&self, span: Duration, selection: &Selection) -> MetricSet

The counter increase over the trailing span (PromQL increase): for each matched counter, cum[now] − cum[now−span] differenced from the retained finest-cadence ring at the finest covering resolution — a continuous/sliding window (e.g. “the last 10 s” off the 1 s ring). Emits counters only, and their values are DELTAS — contrast the running-total readers Self::now / Self::cadence_window / Self::session_lifetime. A rate is increase / span. For the recent latency/value distribution use Self::distribution_over.

pub fn distribution_over( &self, span: Duration, selection: &Selection, ) -> MetricSet

The merged latency/value distribution over the trailing span: for each matched histogram, the HDR reservoir merged across the windows in the span (read p50/p99/mean from it — the PromQL *_over_time quantile family). Same finest-covering-resolution sliding window as Self::increase_over. Emits histograms only — the recent distribution, never a counter increase.

pub fn session_lifetime(&self, selection: &Selection) -> MetricSet

Full canonical session span as of now, filtered by selection. Walks the cascade down at read time:

Per component, COALESCEs the cascade’s disjoint time-slices — every layer’s in-flight prebuffer plus the largest cadence’s retained accumulator (the lifetime buffer) and its last-closed window — then AGGREGATEs the per-component results across components. Coalescing the time dimension keeps the latest cumulative and merges reservoirs, so a session-cumulative counter is the latest running total — not multiplied by the number of cascade sources it appears in.

Per SRD-42 §“Cost rule for recent_window”, only matched metric instances combine — same shape as increase_over / distribution_over.

pub fn select_one<F>(&self, mode: F) -> Result<MetricSet, SelectError>

where F: FnOnce(&Self) -> MetricSet,

Run a query mode and assert exactly one matching Metric per the SRD’s “specific metric” semantics. Returns Err if 0 or

1 matches.