rtb_telemetry/lib.rs
1//! Opt-in anonymous telemetry.
2//!
3//! # Two-level opt-in
4//!
5//! Tool authors enable telemetry at compile time by depending on
6//! this crate (and, via the `rtb` umbrella, by turning on the
7//! `telemetry` Cargo feature). Users opt in separately at runtime by
8//! setting the context's [`CollectionPolicy`] to `Enabled`. The
9//! default is [`CollectionPolicy::Disabled`] — no events emitted,
10//! no machine ID derived, no sink calls.
11//!
12//! # Machine identity
13//!
14//! `MachineId::derive(salt)` returns `sha256(salt || machine_uid)`
15//! hex-encoded. The raw machine ID never leaves this crate. Rotate
16//! the salt to invalidate existing identities.
17//!
18//! # Sinks
19//!
20//! - Always available: [`NoopSink`] (always-Ok drop), [`MemorySink`]
21//! (test fixture), [`FileSink`] (newline-delimited JSON on disk).
22//! - Behind the `remote-sinks` Cargo feature: `HttpSink` (JSON
23//! POST to an HTTPS endpoint) and `OtlpSink` (OTLP/gRPC or
24//! OTLP/HTTP export). Both call [`Event::redacted`] before
25//! serialisation.
26//!
27//! See `docs/development/specs/2026-04-22-rtb-telemetry-v0.1.md` and
28//! `docs/development/specs/2026-04-24-rtb-telemetry-http-otlp-sinks.md`
29//! for the authoritative contracts.
30
31#![forbid(unsafe_code)]
32
33pub mod consent;
34pub mod context;
35pub mod error;
36pub mod event;
37pub mod machine;
38pub mod sink;
39
40#[cfg(feature = "remote-sinks")]
41pub mod http_sink;
42#[cfg(feature = "remote-sinks")]
43pub mod otlp_sink;
44
45pub use consent::{Consent, ConsentState};
46pub use context::{CollectionPolicy, TelemetryContext, TelemetryContextBuilder};
47pub use error::TelemetryError;
48pub use event::Event;
49pub use machine::MachineId;
50pub use sink::{FileSink, MemorySink, NoopSink, TelemetrySink};
51
52#[cfg(feature = "remote-sinks")]
53pub use http_sink::{HttpSink, HttpSinkConfig};
54#[cfg(feature = "remote-sinks")]
55pub use otlp_sink::{OtlpSink, OtlpSinkConfig};