blktrace_rs/lib.rs
1//! Linux block-layer I/O trace capture, straight from the kernel.
2//!
3//! `blktrace_rs` drives the kernel block tracing interface directly (the
4//! `BLKTRACESETUP`/`BLKTRACESTART`/`BLKTRACESTOP`/`BLKTRACETEARDOWN` ioctls
5//! plus the per-CPU relay channels under debugfs), so it needs neither the
6//! `blktrace` nor the `blkparse` command line tools.
7//!
8//! Capturing requires root and a kernel with debugfs. Building this crate
9//! requires `libclang` and the kernel UAPI headers
10//! (`linux/blktrace_api.h`).
11//!
12//! # Example
13//! ```no_run
14//! use blktrace_rs::BlkTrace;
15//!
16//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
17//! let session = BlkTrace::monitor("/dev/sda")?;
18//! // ... do I/O on the device while the tracer runs ...
19//! let report = session.shutdown()?;
20//! for event in &report.events {
21//! if event.is_read() {
22//! println!("read {} bytes at sector {}", event.event.bytes, event.event.sector);
23//! }
24//! }
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! # The `async` feature
30//! The tracing core is inherently blocking (relay channel reads and ioctl
31//! waits). With `features = ["async"]` the crate adds `monitor_async` and
32//! `shutdown_async`, which run that core on the tokio blocking pool so
33//! async callers never stall their executor.
34
35#![warn(missing_docs)]
36// On docs.rs builds this shows feature-gated items (the async API) with
37// cfg badges instead of hiding them.
38#![cfg_attr(docsrs, feature(doc_cfg))]
39
40#[cfg(not(target_os = "linux"))]
41compile_error!("blktrace-rs only supports Linux");
42
43#[cfg(feature = "async")]
44mod async_api;
45mod debugfs;
46mod error;
47mod event;
48mod session;
49mod uapi;
50
51pub use uapi::*;
52
53pub use error::BlktraceError;
54pub use event::BlkTraceEvent;
55pub use session::{BlkTrace, BlkTraceReport, BlkTraceSession};