Skip to main content

TelemetrySink

offline_protocol::telemetry::sink

Trait TelemetrySink 

Source 
pub trait TelemetrySink: Send + Sync {
    // Required method
    fn emit(&self, record: &TelemetryRecord);

    // Provided method
    fn try_emit_protocol_event(&self, _event: &Event) -> bool { ... }
}
Expand description

Sink for structured telemetry records.

Implementations must be cheap when called from hot paths — the SDK does not buffer or rate-limit before dispatch beyond its own sampling layer, so expensive work (I/O, serialization to external formats) should be deferred to a background task owned by the implementor.

§Reentrancy and locking contract

The SDK may invoke TelemetrySink::emit while holding internal locks (most notably the shared-state mutex on the Protocol fan-out path). Implementations MUST NOT:

  • block on slow I/O (network, disk, logging sinks that fsync), or
  • reenter SDK methods on the same OfflineProtocol instance.

A blocking emit stalls every protocol operation that needs the lock. Sinks that need to do real work should push the record onto a bounded channel and return immediately, leaving the heavy lifting to a background task owned by the implementor.

Implementations should also not panic, but the SDK defends against this: every internal dispatch to emit runs under catch_unwind, so a panicking sink is logged at error!, the offending record is dropped, and the protocol continues. A panicking sink therefore loses telemetry and degrades observability but does not corrupt SDK state. Panic isolation only applies under panic = unwind, which every library the SDK ships uses (ADR 0029). A host built with panic = abort aborts the process on any panic, including one from a sink.

§Record passing

The record is passed by reference so implementations that only read fields do not incur a clone. Implementations that need ownership (for example to forward the record to another thread) should call Clone::clone explicitly.

Required Methods§

Source

fn emit(&self, record: &TelemetryRecord)

Dispatches a single telemetry record to the sink.

Provided Methods§

Source

fn try_emit_protocol_event(&self, _event: &Event) -> bool

Offers a protocol event by reference, before it is scrubbed or cloned into a TelemetryRecord.

A sink that returns true has consumed the event and the owned, scrubbed record is never built; one that returns false (the default) receives it through Self::emit as before. The telemetry pipe takes this path: it collects ten of the engine’s events, reads no identifier from any of them, and would otherwise pay a clone of every event it drops. A sink that takes this path must do its own scrubbing, because the engine’s has not run yet.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§