Module pipe 

The telemetry pipe: the client half of the hosted telemetry product, living in the core so every binding ships it from one implementation.

Shape

  emit path (any engine thread, under the engine's locks)
    TelemetrySink::emit ─► classify ─► rollup / pairer / ring buffer
                                             │  one mutex, no I/O
  uploader thread (the one background thread in the workspace)
    drain ring ─► cut batches ─► durable queue ─► HTTPS POST ─► stats

The emit side is a bounded amount of work with no I/O: a gate on an atomic, a match on the record, and a push into a ring buffer under the pipe’s own mutex. The uploader takes that mutex only to take the ring, so the one lock an engine thread can be holding is never held across storage or network I/O.

The store and uploader mutexes are held across a drain, and deliberately: they guard the worker’s own state, the alternative is a queue that can be reordered mid-send, and no engine thread reaches them. That last clause is load-bearing rather than incidental, so every handle method an engine thread can call reads an atomic instead (TelemetryPipe::stats takes only the pipeline mutex, TelemetryPipe::is_durable takes none). A method added here that locks the store would put a caller behind a fifteen-second request.

Nothing here holds a reference to the engine, so a stopped pipe whose final request is still in flight can be dropped without keeping the engine alive. Such a pipe does keep its durable queue until its worker exits, and a pipe started meanwhile over the same storage holds its batches in memory until then: one writer per queue, for the reason store.rs gives.

What leaves the device

Only what WireEventData in wire.rs can express: typed projections with no identifier field, the rollup and session summary the pipe computes, and the engine’s own fixed reason tokens. docs/telemetry.md is the adopter-facing inventory; the golden fixture under tests/ is the pin.

Session boundaries

A session id is minted when telemetry is enabled and rotated on the first foreground after a background; the background edge emits the session summary and asks for a flush. Every buffered event is stamped with the session current at push time, and batches are cut on that stamp before they are cut on size, so a boundary event always carries the session it reports.

Re-exports

pub use host::AppState;

pub use host::TelemetryHost;

pub use host::TelemetryOs;

Modules

host

What the host tells the pipe about itself: the platform every batch envelope names, and the application lifecycle the session boundaries follow.

Structs

TelemetryPipe

A running telemetry pipe. Created by OfflineProtocol::enable_telemetry and stopped by disable_telemetry or by being dropped.

TelemetryStats

A snapshot of the pipe’s counters, for diagnostics and for reconciling an invoice against the device.

Constants

FINAL_FLUSH_BUDGET

How long a final flush (disable, end of session, drop) may block.

PIPE_LOG_TARGET

The tracing target every pipe log line carries. The uniffi crate raises this target to debug while a pipe runs with debug: true.