Skip to main content

tracing_flight_recorder/
lib.rs

1//! In-memory flight recorder for `tracing` events.
2//!
3//! Inspired by Go 1.25's [`trace.FlightRecorder`], this crate provides a
4//! `tracing_subscriber::Layer` that continuously buffers tracing events in a
5//! bounded ring buffer. When something goes wrong — a sync failure, a circuit
6//! breaker opening, a panic — you snapshot the buffer and get the last N
7//! seconds of verbose (DEBUG/TRACE) context that would otherwise be lost.
8//!
9//! Events capture their full span hierarchy (names + fields), so snapshots
10//! preserve request context like `request_id`, `user_id`, and `method`.
11//! Sensitive fields are automatically redacted in both events and spans.
12//!
13//! The recorder pays zero I/O cost until a snapshot is triggered.
14//!
15//! # Quick Start
16//!
17//! ```no_run
18//! use tracing_flight_recorder::{FlightRecorder, FlightRecorderLayer};
19//! use tracing_subscriber::layer::SubscriberExt;
20//! use tracing_subscriber::util::SubscriberInitExt;
21//! use tracing_subscriber::Layer;
22//!
23//! let recorder = FlightRecorder::new(1000);
24//! // CRITICAL: apply per-layer filtering so the recorder sees DEBUG+
25//! // while the console stays at INFO. A global EnvFilter would block
26//! // DEBUG/TRACE events from reaching the recorder layer entirely.
27//! let fr_filter = tracing_subscriber::EnvFilter::new("my_app=debug,warn");
28//! let console_filter = tracing_subscriber::EnvFilter::new("info");
29//! tracing_subscriber::registry()
30//!     .with(FlightRecorderLayer::new(recorder.clone()).with_filter(fr_filter))
31//!     .with(tracing_subscriber::fmt::layer().with_filter(console_filter))
32//!     .init();
33//!
34//! // ... application code ...
35//!
36//! // On error: dump the last 1000 events to disk
37//! recorder.dump_to_file(std::path::Path::new("flight-recorder.json")).ok();
38//! ```
39//!
40//! [`trace.FlightRecorder`]: https://go.dev/blog/flight-recorder
41//!
42//! # Minimal Example
43//!
44//! ```
45//! use tracing_flight_recorder::FlightRecorder;
46//!
47//! let recorder = FlightRecorder::new(50);
48//! assert!(recorder.is_empty());
49//! assert_eq!(recorder.capacity(), 50);
50//! ```
51
52#![cfg_attr(
53    test,
54    allow(
55        clippy::pedantic,
56        clippy::nursery,
57        clippy::unwrap_used,
58        clippy::expect_used,
59        clippy::panic,
60        clippy::exit,
61        clippy::unreachable,
62        clippy::unimplemented,
63        clippy::todo,
64        clippy::panic_in_result_fn,
65        clippy::unchecked_time_subtraction,
66        clippy::as_conversions,
67        clippy::indexing_slicing,
68        clippy::arithmetic_side_effects,
69        clippy::string_slice,
70        clippy::useless_vec,
71        clippy::unused_async,
72    )
73)]
74
75mod capture;
76mod layer;
77mod trigger;
78
79#[cfg(doctest)]
80#[doc = include_str!("../README.md")]
81struct _ReadmeDoctests;
82
83pub use capture::{
84    CapturedEvent, DumpEvent, DumpSource, FlightRecorderDump, SpanContext, DUMP_SCHEMA_VERSION,
85};
86pub use layer::{FlightRecorder, FlightRecorderLayer};
87pub use trigger::{LevelTrigger, OnceTrigger, Trigger};
88
89/// Default ring-buffer capacity (number of events).
90///
91/// At ~200-500 bytes per event, this uses ~200 KB - 500 KB of memory and
92/// captures the most recent 1000 events. The time span covered depends on
93/// your application's event rate — at 10-50 events/sec this is roughly
94/// 20-100 seconds of context.
95pub const DEFAULT_CAPACITY: usize = 1000;