pamoja_telemetry/lib.rs
1#![cfg_attr(not(test), no_std)]
2
3//! Device-side observability for the pamoja SDK.
4//!
5//! Observability is hard on the devices this SDK targets: a node on a metered radio
6//! cannot afford to stream every log line, but it still needs to be diagnosable when
7//! something goes wrong in the field. This crate squares that by separating the
8//! detail a node records from the detail it ships, and by letting the link decide how
9//! much detail is worth sending:
10//!
11//! - [`Event`] - a structured, allocation-free event: a [`Level`], a stable short
12//! code, and an optional measurement.
13//! - [`Reporter`] - records events, ships only those at or above a threshold, and
14//! counts every event it sees so the aggregate picture stays complete even when
15//! detail is held back.
16//! - [`LinkCost`] - maps how costly the link is onto that threshold, so telemetry
17//! degrades gracefully: everything on a free link, only warnings and errors on an
18//! expensive one.
19//! - [`Snapshot`] - a handful of integers a node ships periodically in place of the
20//! raw event stream.
21//!
22//! The crate is `no_std` and allocation-free - it keeps only fixed counters and
23//! `'static` codes - so the same observability runs on a microcontroller and on a
24//! server.
25//!
26//! # Examples
27//!
28//! ```
29//! use pamoja_telemetry::{Event, Level, LinkCost, Reporter};
30//!
31//! let mut reporter = Reporter::new(Level::Trace);
32//!
33//! // The link becomes expensive, so only warnings and errors are worth shipping.
34//! reporter.adapt_to(LinkCost::Expensive);
35//! assert!(reporter.record(Event::info("reading.ok").with_value(4.8)).is_none());
36//! assert!(reporter.record(Event::error("link.lost")).is_some());
37//!
38//! // The detail was dropped, but the counts are intact for the next snapshot.
39//! assert_eq!(reporter.total(), 2);
40//! assert_eq!(reporter.snapshot().dropped, 1);
41//! ```
42
43mod event;
44mod reporter;
45
46pub use event::{Event, Level};
47pub use reporter::{LinkCost, Reporter, Snapshot};