Skip to main content

Crate bitwarden_logging

Crate bitwarden_logging 

Source
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§

CircularBuffer
A thread-safe circular buffer with FIFO eviction.
FlightRecorderConfig
Configuration for the Flight Recorder system.
FlightRecorderEvent
A single log event captured by the Flight Recorder.
FlightRecorderLayer
A tracing subscriber layer that captures log events into the active sink.
LocalBufferSink
Sink that stores events in an in-memory CircularBuffer.
MessageVisitor
Extracts the message and structured fields from a tracing event.

Traits§

FlightRecorderSink
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_recorder has not been called.
without_flight_recorder
Runs future without 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 to skip_all, making field logging opt-in.