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,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. |
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 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
- 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.