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. enable_telemetry additionally needs an api_key and an app_id, both issued by the developer portal; see TelemetryConfig::validate for what it refuses. 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), the engine hashes the peer and group ids it stamps on MLS lifecycle records with the scrub secret (see Self::with_scrub_secret). The telemetry pipe reads the peer id only to pair a handshake’s start with its end, and no identifier has a wire field, so the flag changes what the pipe holds in memory and never what is uploaded. It does not apply to on_event, which delivers every event with its identifiers as they are.

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 MLS lifecycle telemetry out of 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 bounds what an event flood costs, 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 every MLS lifecycle event reaches the telemetry pipe un-sampled and aggregate counts reflect reality, at the cost of everything an un-capped failure spike puts through it. Leave it off unless exact failure counts are needed.

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.

pub fn with_api_key(self, api_key: impl Into<String>) -> Self

Sets the API key the developer portal issued. Sent as a bearer token on every upload; redacted from Debug output.

pub fn with_app_id(self, app_id: impl Into<String>) -> Self

Sets the app id the key was issued against. The ingest cross-checks the two and refuses a mismatch, which stops a key pasted into the wrong app from misattributing its data.

pub fn with_app_version(self, app_version: impl Into<String>) -> Self

Sets the application’s own version string, stamped on every batch.

pub fn with_debug(self, debug: bool) -> Self

Logs every wire event at debug under the pipe’s tracing target, so an adopter can see exactly what leaves the device.

pub fn with_flush_interval(self, flush_interval: Duration) -> Self

Sets the background flush cadence. Not below MIN_FLUSH_INTERVAL.

pub fn with_max_batch_bytes(self, max_batch_bytes: usize) -> Self

Sets the size trigger for an early flush and the largest batch cut.

pub fn with_max_buffered_records(self, max_buffered_records: usize) -> Self

Sets the ring-buffer capacity.

pub fn with_include_device_id(self, include_device_id: bool) -> Self

Stamps the stable per-install id on every batch, so the ingest counts distinct devices rather than distinct sessions.

Off by default because it is a disclosure decision: a stable per-install identifier is a “device or other ID” under Google Play’s definition and a NSPrivacyCollectedDataTypeDeviceID under Apple’s. See docs/privacy.md.

pub fn api_key(&self) -> Option<&str>

Returns the configured API key.

pub fn app_id(&self) -> Option<&str>

Returns the configured app id.

pub fn app_version(&self) -> &str

Returns the application version stamped on batches.

pub fn debug(&self) -> bool

Returns whether the debug tap is on.

pub fn flush_interval(&self) -> Duration

Returns the background flush cadence.

pub fn max_batch_bytes(&self) -> usize

Returns the size trigger and batch ceiling.

pub fn max_buffered_records(&self) -> usize

Returns the ring-buffer capacity.

pub fn include_device_id(&self) -> bool

Returns whether the per-install id is stamped on batches.

pub fn validate(&self) -> Result<(), &'static str>

Checks the fields enable_telemetry depends on, naming the first one that fails.

Refused: a missing or empty api_key or app_id, or one that is not printable ASCII (a header value the ingest could never read, which would otherwise be retried forever as a network error); an empty app_version; a max_batch_bytes of zero or above MAX_BATCH_BYTES_LIMIT; a max_buffered_records of zero; a flush_interval below MIN_FLUSH_INTERVAL, which is reported under the name every binding gives it, flush_interval_ms.

Trait Implementations

impl Clone for TelemetryConfig

fn clone(&self) -> Self

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.