embeprom 0.1.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, 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.
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 a single atomic op. 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/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) — it's that u64/i64 atomics are native on Cortex-M while f64 atomics need a CAS-retry loop, and embedded counters (packet counts, byte counts) are naturally integral and want the cheaper, exact path.

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, Histogram, HistogramVec. Disable on firmware that never needs floats to skip f64 atomics/formatting.
cs-atomics Route 64-bit atomics through critical-section instead of native CAS. Required on targets without 64-bit atomic CAS, e.g. thumbv6m-none-eabi (Cortex-M0).
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>.

no_std / embedded support

Builds and links on real Cortex-M targets with #![forbid(unsafe_code)] throughout. Verified against thumbv7em-none-eabihf (native 64-bit CAS) and thumbv6m-none-eabi (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.