Install a sink and buffer events offline
Last updated
See what the mesh is doing without breaking the privacy model. This guide covers installing an opt-in telemetry sink, what lands on the event stream, and how events buffer offline and flush when a connection returns.
An observability path that installs a telemetry sink, receives one ordered stream of protocol events, MLS lifecycle, transport transitions, and routing decisions, buffers them on a disconnected device, and forwards them to your backend when any path appears.
How telemetry works
Most SDKs phone home by default. This one does the opposite: the protocol emits nothing on its own. Telemetry exists only when your application installs a sink, and the data goes only where that sink sends it. Opting in is a deliberate choice, and opting out is the absence of code.
Once a sink is installed, a single ordered stream carries everything the protocol sees, and on a device with no connection those events buffer with store and forward until a path appears. See offline telemetry, explained for the full event catalog.
Prerequisites
- The SDK installed and initialized, from the quickstart.
- A destination for events: a log file, a local store, or a backend in your existing observability stack.
- A clear opt-in. The protocol emits nothing until you install a sink, so telemetry is a deliberate choice.
Steps
Telemetry exists only when your application installs a sink. A sink is application code that receives the event stream, so the data goes only where you send it. With no sink installed, the protocol emits nothing and sends no data anywhere.
One ordered stream carries protocol events, MLS lifecycle, transport-state transitions, routing decisions, and device-capability changes. A delivery event, for example, carries the message ID, the measured latency in milliseconds, and the hop count; a failure carries the reason and retry count.
On a disconnected device, events buffer on-device through the outage with store and forward. Nothing is lost to the gap in connectivity, so undelivered is as diagnosable as delivered.
Buffered events forward when any path appears: a mesh route to a connected peer, or the device regaining its own internet link. From there your sink pushes them into whatever backend your stack already uses.
The exact call to install a sink and the shape of each event are in the API reference. Follow the documentation for the signatures rather than guessing.
What you get
Field-grade observability that respects the opt-in model: one stream of protocol events, MLS lifecycle, transport transitions, and routing decisions, buffered through outages and delivered to your own backend, so an undelivered message is as diagnosable as a delivered one and nothing is lost to a gap in connectivity.
Next steps
Offline telemetry FAQ
Does telemetry compromise the privacy model?
No. The protocol emits nothing on its own. Telemetry exists only when your application installs a sink, and the data goes only where that sink sends it. It is fully opt-in.
What is in the event stream?
Protocol events, MLS lifecycle, transport-state transitions, routing decisions, and device-capability changes, as structured events on one ordered stream.
How does data get out of a disconnected device?
With store and forward: events buffer on-device through the outage and forward when any path appears, a mesh route to a connected peer or the device regaining its own internet link. Nothing is lost to the gap in connectivity.
Is there overhead when no sink is installed?
Emission is gated at the source: with no sink installed, the protocol emits nothing, so an application that never opts in ships no telemetry code path in practice and sends no data anywhere.
