tracing_actions/
lib.rs

1//! A measured, convenient approach to building traces.
2//!
3//! [`tracing-actions`] is a trace recording toolbox.
4//! It records your live spans on the heap and offers you a visitor function
5//! which is called once per span with the ActionSpan.
6//!
7//! Action traces, being heap-allocated, are held in an object pool to mitigate
8//! the cost of allocations. While low overhead is a goal of tracing-actions,
9//! 0-overhead is not. This is a tool for convenience first and performance second.
10//!
11//! # Examples
12//!
13//! ## K-log
14//! ```rust
15//! use tracing_actions;
16//! use log;
17//!
18//! // First, we implement k-logging.
19//! struct KLog {
20//!   k: usize,
21//!   n: std::sync::atomic::AtomicUsize,
22//! }
23//! impl tracing_actions::TraceSink for KLog {
24//!     fn sink_trace(&self, action_span: &mut tracing_actions::ActionSpan) {
25//!         if self.n.fetch_add(1, std::sync::atomic::Ordering::Relaxed) % self.k == 0 {
26//!             log::info!("trace: {action_span:?}")
27//!         }
28//!     }
29//! }
30//!
31//! // Next, we configure a subscriber.
32//! let level = "debug".parse().unwrap();
33//! let k_logging_subscriber = tracing_actions::ActionTraceSubscriber::new(
34//!     level,
35//!     KLog { k: 42, n: Default::default() },
36//!     tracing_actions::span_constructor::LazySpanCache::default(),
37//! );
38//!
39//! // Finally, we install the subscriber.
40//! tracing::subscriber::set_global_default(k_logging_subscriber)
41//!     .expect("I should be able to set the global trace subscriber");
42//!
43//! // Now the rest of your application will k-log ActionSpans.
44//! ```
45//!
46
47mod action_span;
48mod action_trace_subscriber;
49
50pub mod span_constructor;
51
52pub use action_span::ActionEvent;
53pub use action_span::ActionSpan;
54pub use action_span::AttributeValue;
55pub use action_span::SpanStatus;
56pub use action_span::TraceKind;
57pub use action_trace_subscriber::ActionTraceSubscriber;
58pub use action_trace_subscriber::TraceSink;