Struct TelemetryConfig 

#[non_exhaustive]
pub struct TelemetryConfig { /* private fields */ }

Runtime configuration for the telemetry subsystem.

Constructed via TelemetryConfig::default (which locks in the privacy-preserving defaults) and refined with the with_* builder methods. Fields are crate-private; read them through the accessor methods and mutate them through the builder methods — this keeps a single idiom for configuration and prevents mid-run mutation of identity-correlation parameters like the scrub secret (which would invalidate every previously emitted opaque identifier).

The struct is #[non_exhaustive] to preserve room for future knobs.

Implementations

impl TelemetryConfig

pub fn with_scrub_ids(self, scrub_ids: bool) -> Self

Sets the identifier-scrubbing flag.

When true (the default), long-lived pseudonymous identifiers (peer_id, user_id, app_id, group_id) are hashed before crossing the telemetry sink boundary — third-party sinks (analytics, crash reporters) must not receive raw identifiers by default.

pub fn with_mls_verbosity(self, mls_verbosity: MlsVerbosity) -> Self

Sets the MLS lifecycle verbosity tier.

pub fn with_metrics_cadence(self, cadence: Option<Duration>) -> Self

Sets the cadence for periodic MetricsSnapshot emission. None disables periodic emission entirely (apps fall back to pull-based access via TransportManager::metrics()).

pub fn with_scrub_secret(self, secret: Option<[u8; 16]>) -> Self

Sets the opaque-identifier hashing secret.

Supplying Some(secret) pins an explicit, caller-owned secret and always takes precedence over the SDK-managed fallback below.

Supplying None (the default) leaves the secret unset in the config. In that case the SDK manages the fallback for you: the first time secure storage is provided via OfflineProtocol::initialize_mls, the SDK loads — or, on first run, generates and persists — a stable per-install secret. This makes opaque identifiers survive process restarts, so backend telemetry can count distinct devices across sessions. Until storage is available (or if storage is never provided), the SDK uses a random per-instance secret derived at protocol construction.

Precedence: explicit config secret > SDK-managed persistent secret > random per-instance secret.

Do not share the secret across tenants, and do not rotate it mid-run — rotation invalidates every previously emitted opaque identifier and breaks correlation on the receiving side. For the SDK-managed fallback this means: do not back two tenants with the same storage, and do not clear the scrub_secret storage entry within a measurement window.

pub fn scrub_ids(&self) -> bool

Returns whether identifier scrubbing is enabled.

pub fn mls_verbosity(&self) -> MlsVerbosity

Returns the configured MLS lifecycle verbosity tier.

pub fn metrics_cadence(&self) -> Option<Duration>

Returns the configured periodic metrics-snapshot cadence.

pub fn with_routing_diagnostic(self, routing_diagnostic: bool) -> Self

Sets whether RoutingDecision records should carry the full per-transport score breakdown.

When true, every emitted crate::telemetry::RoutingDecision::scores is populated with the seven-factor offline_protocol_router::TransportScore for each ranked transport. When false (the default), scores is empty — the hot path avoids the per-emission vector allocation and Diagnostic-tier consumers simply see an empty vector.

Leaf identifiers are not affected: this knob only gates the scoring-factor detail, not identity fields.

pub fn routing_diagnostic(&self) -> bool

Returns whether routing records should carry diagnostic score detail.

pub fn with_mls_sampling_bypass(self, mls_sampling_bypass: bool) -> Self

Opts the installed sink out of MLS lifecycle event rate limiting.

By default (false), high-volume MLS lifecycle events (mls.decryption_failed, mls.session_missing) pass through a best-effort fixed-window limiter that caps emission per peer+kind. The cap protects naïve sinks from event floods, but it also clips genuine failure spikes to the per-window ceiling — an aggregating backend cannot tell a real burst of N failures apart from the cap.

Setting this to true disables that limiter so a telemetry-grade sink receives every MLS lifecycle event un-sampled, and aggregate counts reflect reality. Only enable it for sinks that apply their own backpressure (for example, pushing onto a bounded channel and draining on a background task per the TelemetrySink contract) — an unbuffered sink that does real work inline can be overwhelmed by an un-capped failure spike.

This knob only affects MLS-event rate limiting; it does not change identifier scrubbing, verbosity, or any other field.

pub fn mls_sampling_bypass(&self) -> bool

Returns whether MLS lifecycle event rate limiting is bypassed.

Trait Implementations

impl Clone for TelemetryConfig

fn clone(&self) -> TelemetryConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TelemetryConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TelemetryConfig

fn default() -> Self

Returns the “default value” for a type.