Expand description
§Bitwarden Logging
Flight Recorder infrastructure for capturing and exporting diagnostic logs.
Internal crate for the bitwarden crate. Do not use.
§Working With FlightRecorder
The Flight Recorder captures tracing events into a global circular buffer so they can be exported for diagnostics without requiring the caller to hold a direct reference to the buffer. Once IPC forwarding is enabled (see Aggregation over IPC), events go to the collector instead and the local buffer keeps only events from the IPC stack.
§Initialization
Call init_flight_recorder during SDK startup and add the returned layer to your tracing
subscriber:
use bitwarden_logging::{init_flight_recorder, FlightRecorderConfig};
use tracing_subscriber::{layer::SubscriberExt as _, util::SubscriberInitExt as _};
let flight_recorder_layer = init_flight_recorder(FlightRecorderConfig::default());
tracing_subscriber::registry()
.with(flight_recorder_layer)
.init();The default configuration retains 1 000 events at DEBUG level. Use FlightRecorderConfig::new for
custom settings.
§Reading events
Once initialized, events can be read from anywhere in the process:
use bitwarden_logging::{read_flight_recorder, flight_recorder_count};
let count = flight_recorder_count();
let events = read_flight_recorder();Both functions return safe defaults (0 / empty Vec) if the recorder has not been initialized.
They read only this context’s buffer. In a forwarder, use ipc::read_flight_recorder_aggregated to
include the collector’s events.
§WASM usage
In bitwarden-wasm-internal, the recorder is automatically initialized by init_sdk(). TypeScript
consumers access it through FlightRecorderClient:
import { FlightRecorderClient } from "@aspect/bitwarden-wasm-internal";
const recorder = new FlightRecorderClient();
const count = recorder.count();
const events = await recorder.read();Each FlightRecorderEvent contains timestamp, level, target, message, fields, and
process.
§Aggregation over IPC
The ipc cargo feature lets clients with several contexts collect their events in one context over
bitwarden-ipc. One context is the collector (browser background, desktop main) and the others are
forwarders that send their events to it. Forwarders keep events from the IPC stack itself locally. A
forwarder starts sending once the collector answers a discover request, so the collector must
register the discover handler. Until then, events stay in the forwarder’s local buffer. The
collector labels each event’s process with the context it came from, and only accepts messages
from its own client’s forwarders.
The WASM bindings expose this as enableFlightRecorderCollection and
enableFlightRecorderForwarding. In a forwarder, recorder.read() returns the collector’s events
followed by its own, falling back to its own events if the collector does not answer.
Modules§
- circular_
buffer 🔒 - Thread-safe circular buffer implementation.
- config 🔒
- Configuration for the Flight Recorder.
- event 🔒
- Flight Recorder event definitions.
- global 🔒
- Global Flight Recorder buffer and convenience accessors.
- ipc
- Aggregation of Flight Recorder events from several contexts of one client over
[
bitwarden_ipc]. - layer 🔒
- Tracing subscriber layer for Flight Recorder.
- sink 🔒
- Destinations for captured Flight Recorder events.
- suppress 🔒
- Suppression of Flight Recorder capture while a future is polled.
- visitor 🔒
- Visitor for extracting fields from tracing events.
Structs§
- Circular
Buffer - A thread-safe circular buffer with FIFO eviction.
- Flight
Recorder Config - Configuration for the Flight Recorder system.
- Flight
Recorder Event - A single log event captured by the Flight Recorder.
- Flight
Recorder Layer - A tracing subscriber layer that captures log events into the active sink.
- Local
Buffer Sink - Sink that stores events in an in-memory
CircularBuffer. - Message
Visitor - Extracts the message and structured fields from a tracing event.
Traits§
- Flight
Recorder Sink - Destination for events captured by the Flight Recorder.
Functions§
- flight_
recorder_ count - Get the current event count without reading event contents.
- get_
flight_ recorder_ buffer - Get the global Flight Recorder buffer.
- init_
flight_ recorder - Initialize the global Flight Recorder.
- read_
flight_ recorder - Read all events from the global Flight Recorder buffer.
- set_
flight_ recorder_ sink - Replace the global Flight Recorder’s active sink. Events already in the local buffer stay
there. No-op if
init_flight_recorderhas not been called. - without_
flight_ recorder - Runs
futurewithout recording any events it emits while being polled, from any crate or target. Work the future hands to other spawned tasks is not covered. - write_
flight_ recorder - Write a single externally-sourced event (e.g. from TypeScript) into the global Flight Recorder’s active sink, honoring the configured level floor.
Attribute Macros§
- instrument
- Drop-in replacement for
#[tracing::instrument]that defaults toskip_all, making field logging opt-in.