rtb-telemetry

Part of the phpboyscout Rust toolkit — small, framework-free crates extracted from rust-tool-base.

Opt-in anonymous usage telemetry with pluggable sinks. Events carry a salted SHA-256 machine identity (the raw machine ID never leaves the crate), an RFC-3339 UTC timestamp, and caller-supplied attributes. Collection is disabled by default at every layer: tool authors opt in at compile time by depending on the crate, users opt in at runtime via CollectionPolicy::Enabled — persisted through the consent module.

use rtb_telemetry::{CollectionPolicy, MemorySink, TelemetryContext};
use std::sync::Arc;

let sink = Arc::new(MemorySink::new());
let telemetry = TelemetryContext::builder()
    .tool("mytool")
    .tool_version("1.0.0")
    .salt(concat!(env!("CARGO_PKG_NAME"), ".telemetry.v1"))
    .sink(sink.clone())
    .policy(CollectionPolicy::Enabled)
    .build();

telemetry.record("command.invoke").await?;

Built-in sinks: NoopSink, MemorySink, FileSink (newline-delimited JSON). The remote-sinks Cargo feature adds HttpSink (JSON POST over HTTPS) and OtlpSink (OTLP/gRPC + OTLP/HTTP export). Every built-in sink runs rtb-redact over Event::args and Event::err_msg before serialisation.

• Docs: https://telemetry.rust.phpboyscout.uk
• API reference: https://docs.rs/rtb-telemetry
• Crate: https://crates.io/crates/rtb-telemetry

Development

just ci runs the full local gate (fmt, clippy, nextest, doc, deny). Run clippy and nextest with --all-features as well to cover the remote-sinks sinks. Tests include a cucumber BDD suite (tests/bdd.rs); the MachineId::derive scenario reads /etc/machine-id (CI seeds a stable one). Releases are cut by release-plz from Conventional Commits — do not tag manually.

License

MIT