embeprom 0.3.0

Heapless Prometheus metrics for no_std embedded systems
Documentation

embeprom

crates.io docs.rs license

Prometheus-style metrics for no_std embedded devices, with no heap allocation. Declare metrics as a real, strongly-typed struct; record them from anywhere via a global accessor; export them in Prometheus text exposition format through a pull-based renderer that's easy to wire into picoserve (or any other HTTP server, or any byte sink at all).

Why

Existing Rust metrics crates (prometheus, metrics) assume a heap and a long-running process registering a collector somewhere. On a microcontroller there's no heap, often no threads worth speaking of, and firmware crates want to export metrics without every caller threading a collector handle through their APIs. embeprom is built around those constraints:

  • no_std, no heap. Every metric's storage is a fixed-size static; heapless collections back everything with runtime cardinality (labels).
  • Global recording, no object to pass around. some_crate::metrics::get().foo.inc() works from anywhere some_crate is visible.
  • Strongly typed declarations. Each metrics group is a real struct with named fields, generated by a macro_rules! macro (no proc-macro dependency) — full IDE autocomplete and find-usages on every metric.
  • One central export point. A [Renderer] walks every registered group via dynamic dispatch and streams Prometheus text format out, without the exporter knowing any crate's concrete metrics type.
  • Bounded cardinality. Labeled metrics (CounterVec, GaugeVec, GaugeF64Vec, HistogramVec) declare their maximum number of distinct label combinations as a const generic; once full, new combinations use unrendered no-op sink handles and existing series keep updating — never a heap-exhaustion surprise or a required error branch.

Quickstart

// Declare in a dedicated module. The macro expands to a real struct with
// autocomplete-able fields plus fixed `METRICS` and `get` items.
/// Wi-Fi driver metrics.
pub mod metrics {
    embeprom::metrics! {
        namespace = "wifi";

        /// Total Wi-Fi frames transmitted.
        packets_sent: Counter,
        /// Last measured RSSI in dBm.
        rssi_dbm: Gauge,
        /// Disconnects, by reason.
        #[labels("reason")]
        disconnects_total: CounterVec<4>,
        /// TX completion latency in microseconds.
        #[buckets(100, 500, 1000, 5000)]
        tx_latency_us: IntHistogram,
    }
}

// Record — from anywhere, no collector object to pass around. The first
// call to `metrics::get()` self-registers the group; no setup step needed.
metrics::get().packets_sent.inc();
metrics::get().disconnects_total.inc(&["beacon_timeout"]);
metrics::get().tx_latency_us.observe(120);

// Export — a pull-based cursor, synchronous and `no_std`, so it has no
// opinion about how bytes reach the network.
let mut renderer = embeprom::Renderer::new();
while let Some(line) = renderer.next_line().unwrap() {
    // send `line.as_bytes()` to whatever sink you have
}

When label values are stable, bind the series once during initialization and retain the returned handle on the hot path:

let beacon_timeouts = metrics::get()
    .disconnects_total
    .with(&["beacon_timeout"]);

// Updates the bound counter directly: no repeated label construction or
// label-store lookup.
beacon_timeouts.inc();

The same pattern works for gauge and histogram vectors. Convenience methods such as .inc(&[...]) and .observe(&[...], value) perform the lookup on every call and are intended for infrequent or genuinely dynamic labels.

The second Renderer const generic is the line-buffer capacity, independently tunable from the registry capacity: Renderer::with_line_capacity::<512>(). An undersized buffer returns RenderError::LineTooLong once with the exact required size, skips that line, and lets subsequent next_line calls continue.

With consistent-histograms, the third const generic bounds reusable per-series histogram snapshot scratch (16 finite buckets by default). Tune both renderer buffers with Renderer::with_capacities::<LINE, HIST_BUCKETS>().

Output (Prometheus text exposition format):

# HELP wifi_packets_sent Total Wi-Fi frames transmitted.
# TYPE wifi_packets_sent counter
wifi_packets_sent 1
# HELP wifi_rssi_dbm Last measured RSSI in dBm.
# TYPE wifi_rssi_dbm gauge
wifi_rssi_dbm 0
# HELP wifi_disconnects_total Disconnects, by reason.
# TYPE wifi_disconnects_total counter
wifi_disconnects_total{reason="beacon_timeout"} 1
# HELP wifi_tx_latency_us TX completion latency in microseconds.
# TYPE wifi_tx_latency_us histogram
wifi_tx_latency_us_bucket{le="100"} 1
wifi_tx_latency_us_bucket{le="500"} 1
wifi_tx_latency_us_bucket{le="1000"} 1
wifi_tx_latency_us_bucket{le="5000"} 1
wifi_tx_latency_us_bucket{le="+Inf"} 1
wifi_tx_latency_us_sum 120
wifi_tx_latency_us_count 1

See the crate docs for the full guide, including registration semantics, all supported metric kinds, and a ready-to-use picoserve Chunks adapter.

Design

For anyone (human or agent) picking this codebase up cold — the decisions below aren't visible from the API alone, and each one shapes how the rest of the crate is built. They're kept here rather than scattered across doc comments so there's one place to read before making a change that might fight one of them.

Module map (src/):

Module Role
counter.rs, gauge.rs, histogram.rs Scalar metric storage — thin wrappers over portable_atomic atomics.
series.rs Borrowed histogram series handles (IntHistSeries, HistSeries) shared by scalars and vecs.
labels.rs, vec.rs Labeled metric collections (CounterVec etc.) — the const-generic-bounded, critical-section-guarded label→slot map.
erased.rs The MetricGroup/MetricRef/MetricDesc object-safe traits used for dynamic dispatch — the seam between "a crate's concrete metrics struct" and "the renderer that doesn't know about it."
registry.rs The fixed-capacity global registry, plus OnceRegister for lazy self-registration.
render.rs The pull-based Renderer state machine that walks the registry and emits Prometheus text format.
macros.rs The metrics! macro — the only place that ties a user's declaration syntax to the generated struct/impl.
escape.rs, value.rs, config.rs Leaf utilities: exposition-format escaping/validation, the type-erased sample Value, and feature-gated capacity constants.

Explicit and lazy registration share one fallible primitive. A group can be registered explicitly (register(), returning RegistryFull for startup code to handle) or lazily (OnceRegister::ensure, called from the macro-generated accessor on first use — logs at most once and never panics, since by then it is usually a hot-path metric write). Both ultimately call Registry::register, which dedups groups by static data address so a group can go through either or both paths without being double-counted.

The built-in registry is the default target. A caller-owned Registry<N> can have any capacity; metrics! { registry = REGISTRY; ... } preserves lazy registration when that registry is visible to the declaration module, and Renderer::from_registry(&REGISTRY) renders it directly. metrics! { registration = manual; ... } disables get() registration so the same module's METRICS static can be registered explicitly with multiple registries.

The renderer is a pull-based cursor, not a push/callback, because of an async/sync impedance mismatch that only shows up at the integration boundary. embeprom must stay no_std and synchronous (point 1 of the design goals), but the natural consumer — picoserve's ChunkWriter — is async. A core::fmt::Write impl can't .await a flush; neither can a FnMut(&[u8]) callback. Inverting control (Renderer::next_line returns one complete line, and the caller can .await before asking for another) is what makes a sync renderer usable from an async caller without threading a runtime through the crate. HTTP framing and write buffering stay at the integration boundary rather than becoming a second cursor inside the renderer.

metrics! is macro_rules!, not a proc-macro, and that constraint drives several odd-looking tricks in macros.rs. No syn/quote/workspace, so: indexed access into a variable-length metric list is a generated if i == 0 { return .. } i -= 1; chain (no arithmetic on repetitions in stable macro_rules!); counting repetitions into const-generic position uses the length of a generated array of stringified tokens. Histogram bucket bounds remain typed through the type-erased renderer boundary and are formatted as Prometheus values there, so Rust-specific literal spelling never leaks into le="..." labels. If a change seems to need real parsing/codegen, it probably means outgrowing plain macro_rules! — that trade was made deliberately (see the design conversation this crate was built from), so revisit it as a decision, not a workaround.

Atomics are the default; critical_section is reserved for genuinely compound operations. Every scalar update (Counter::inc, Gauge::set, and each histogram bucket/sum/count individually) is expressed as a single atomic op. Whether that operation is native or lock-backed is target-dependent. critical_section::with normally appears only where an operation is inherently compound: label-slot lookup-or-insert and registry mutation/snapshot. The optional consistent-histograms feature also treats one histogram observation as a compound update and copies one complete series into renderer-owned scratch under a brief critical section. The lock is released before formatting or yielding the first line, so it is never held across a next_line boundary or an async await. If you're adding a metric operation and reaching for a critical section, check first whether it can be a single atomic op instead — that's the fast path this crate is built to guarantee.

Cardinality is bounded by construction, and "full" is a silent drop, not an error. CounterVec<N> et al. take N as a const generic; once N distinct label combinations exist, .with() returns an opaque, unrendered sink handle whose updates are no-ops; oversized rendered label blocks behave the same way. Existing series keep working. This was a deliberate no_std tradeoff: recording metrics never requires callers to branch on capacity, and there is no heap to grow into. Sink reads return zero and sink values never appear in a scrape.

Int/float metric types are split on purpose. Counter is always u64; Gauge/Histogram have separate GaugeF64/GaugeF64Vec/Histogram<B> (float) and integer-backed defaults, gated behind the float feature. This isn't parity with the Prometheus wire format (which is float64-only): embedded counters are naturally integral and retain exact integer values internally, while floating-point updates require a CAS-retry loop. Native 64-bit atomics are not available on every Cortex-M target; see the interrupt-safety warning below for the consequences of the lock-backed fallback.

Testing has to substitute for hardware-in-the-loop. There's no CI rig with real Cortex-M boards, so "works" is established by: unit tests on host (cargo test, using critical-section's std backend); a line-cursor golden test that reassembles next_line output and diffs it against the full expected exposition; explicit exact-capacity and overflow-recovery tests; and compiling and linking (not just running) a real firmware binary in examples/no_std_check against thumbv7em-none-eabihf and thumbv6m-none-eabi.

Serving over HTTP

embeprom has no dependency on picoserve (or any HTTP server) — its renderer is a plain pull-based cursor. Bridging it to picoserve's chunked response body is a ~10-line adapter; see the Serving over HTTP with picoserve section of the crate docs for the full example.

Feature flags

Feature Effect
float (default) f64-backed GaugeF64, GaugeF64Vec, Histogram, HistogramVec. Disable on firmware that never needs floats to skip f64 atomics/formatting.
cs-atomics Supply atomic compare-and-swap through critical-section on targets that lack pointer-width CAS, e.g. thumbv6m-none-eabi (Cortex-M0). This does not replace the lock-backed 64-bit fallback on targets such as thumbv7em-none-eabihf; see below.
consistent-histograms Serialize scalar and vector histogram observations, then copy each series into renderer-owned scratch under one brief critical section. All _bucket/_sum/_count lines come from that immutable snapshot; scratch defaults to MAX_HISTOGRAM_BUCKETS finite buckets and is tunable per renderer.
log Log via the log crate (once per metric group, not per write) if a group fails to self-register because the registry is full.
std Pull in critical-section's std backend; mainly useful for host-side testing.
label-value-{64,128} Increase the default 48-byte rendered label-block budget crate-wide. Feature unification selects the largest enabled value; per-metric capacities use the vec types' const generics or macro attribute #[label_bytes(24)].
max-groups-{32,64,128,256,512} Increase the default 16-group global registry capacity. Feature unification selects the largest enabled value; smaller applications can install a caller-owned Registry<N>.

Interrupt-context safety

Warning: metric access is not interrupt-safe on targets that have pointer-width atomic compare-and-swap but lack native 64-bit atomics.

On those targets, portable-atomic implements the u64, i64, and f64 storage used by metrics with global locks. thumbv7em-none-eabihf is one affected target. If foreground code is preempted while it holds one of those locks and an interrupt handler accesses the same metric — or another metric mapped to the same fallback lock — the interrupt handler spins forever while the foreground code cannot resume to release the lock.

The cs-atomics feature does not fix this case: it supplies CAS on targets that lack CAS, such as thumbv6m-none-eabi, but does not redirect the 64-bit global-lock fallback on a target that already has pointer-width CAS. Likewise, consistent-histograms is not a general workaround for counters and gauges. No embeprom feature currently removes this restriction on affected targets.

Until the storage implementation changes, do not access or render metrics from an interrupt handler on an affected target when foreground code can also access metrics. The upstream portable-atomic documentation describes the fallback choices and the system-level requirements of its interrupt-disabling alternatives.

no_std / embedded support

Builds and links on real Cortex-M targets with #![forbid(unsafe_code)] throughout. Verified against thumbv7em-none-eabihf (lock-backed 64-bit atomics, subject to the interrupt-context restriction above) and thumbv6m-none-eabi (CAS supplied via cs-atomics) — see examples/no_std_check for a minimal cortex-m-rt binary exercising declaration, recording, and rendering end to end.

MSRV: 1.87 (floor set by the heapless dependency).

License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.