embeprom
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-sizestatic;heaplesscollections back everything with runtime cardinality (labels).- Global recording, no object to pass around.
some_crate::metrics::get().foo.inc()works from anywheresome_crateis 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.
// Record — from anywhere, no collector object to pass around. The first
// call to `metrics::get()` self-registers the group; no setup step needed.
get.packets_sent.inc;
get.disconnects_total.inc;
get.tx_latency_us.observe;
// Export — a pull-based cursor, synchronous and `no_std`, so it has no
// opinion about how bytes reach the network.
let mut renderer = new;
while let Some = renderer.next_line.unwrap
When label values are stable, bind the series once during initialization and retain the returned handle on the hot path:
let beacon_timeouts = get
.disconnects_total
.with;
// 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(®ISTRY) 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
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
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.