# pamoja-telemetry
Device-side observability for pamoja: structured leveled events and counters that degrade gracefully on metered links, no_std and allocation-free.
<a href="https://pamoja.molex.cloud/docs/reference/rust/pamoja_telemetry/index.html"><img height="28" alt="API reference" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg"></a>
<a href="https://pamoja.molex.cloud/docs/guides/telemetry.html"><img height="28" alt="read the guide" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg"></a>
<a href="https://crates.io/crates/pamoja-telemetry"><img height="28" alt="crates.io" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-cratesio.svg"></a>
<a href="https://docs.rs/pamoja-telemetry"><img height="28" alt="docs.rs" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docsrs.svg"></a>
## The same capability in every language
| Rust | [`pamoja-telemetry`](https://crates.io/crates/pamoja-telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_telemetry/index.html), [docs.rs](https://docs.rs/pamoja-telemetry), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-telemetry) |
| TypeScript | [`@pamoja/telemetry`](https://www.npmjs.com/package/@pamoja/telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-telemetry) |
| Python | [`pamoja-telemetry`](https://pypi.org/project/pamoja-telemetry/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-telemetry) |
| C# | [`Pamoja.Telemetry`](https://www.nuget.org/packages/Pamoja.Telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-telemetry) |
Device-side observability for the pamoja SDK.
Observability is hard on the devices this SDK targets: a node on a metered radio
cannot afford to stream every log line, but it still needs to be diagnosable when
something goes wrong in the field. This crate squares that by separating the
detail a node records from the detail it ships, and by letting the link decide how
much detail is worth sending:
- `Event` - a structured, allocation-free event: a `Level`, a stable short
code, and an optional measurement.
- `Reporter` - records events, ships only those at or above a threshold, and
counts every event it sees so the aggregate picture stays complete even when
detail is held back.
- `LinkCost` - maps how costly the link is onto that threshold, so telemetry
degrades gracefully: everything on a free link, only warnings and errors on an
expensive one.
- `Snapshot` - a handful of integers a node ships periodically in place of the
raw event stream.
The crate is `no_std` and allocation-free - it keeps only fixed counters and
`'static` codes - so the same observability runs on a microcontroller and on a
server.
**Examples**
```rust
use pamoja_telemetry::{Event, Level, LinkCost, Reporter};
let mut reporter = Reporter::new(Level::Trace);
// The link becomes expensive, so only warnings and errors are worth shipping.
reporter.adapt_to(LinkCost::Expensive);
assert!(reporter.record(Event::info("reading.ok").with_value(4.8)).is_none());
assert!(reporter.record(Event::error("link.lost")).is_some());
// The detail was dropped, but the counts are intact for the next snapshot.
assert_eq!(reporter.total(), 2);
assert_eq!(reporter.snapshot().dropped, 1);
```
## License
MIT - part of the [pamoja](https://github.com/molexxxx/pamoja) workspace: one memory-safe Rust core with bindings for every language.