Skip to main content

Crate blktrace_rs

Crate blktrace_rs 

Source
Expand description

Linux block-layer I/O trace capture, straight from the kernel.

blktrace_rs drives the kernel block tracing interface directly (the BLKTRACESETUP2/BLKTRACESETUP/BLKTRACESTART/BLKTRACESTOP/ BLKTRACETEARDOWN ioctls plus the per-CPU relay channels under debugfs), so it needs neither the blktrace nor the blkparse command line tools.

Sessions prefer the v2 trace API, which since Linux 6.19 is the only format that records write-zeroes requests (they got their own trace category, above the v1 ceiling, in commit bc49af56eea8; v1 sessions silently drop such records). On older kernels the setup falls back to the v1 API automatically, where write-zeroes requests are recorded as ordinary writes; events are normalized into BlkTraceEvent either way.

Capturing requires root and a kernel with debugfs. Building needs neither libclang nor kernel UAPI headers: every UAPI layout is hand-written and pinned to upstream header commits.

§Example

use blktrace_rs::BlkTrace;

let session = BlkTrace::monitor("/dev/sda")?;
// ... do I/O on the device while the tracer runs ...
let report = session.shutdown()?;
for event in &report.events {
    if event.is_read() {
        println!("read {} bytes at sector {}", event.bytes, event.sector);
    }
}

§The async feature

The tracing core is inherently blocking (relay channel reads and ioctl waits). With features = ["async"] the crate adds monitor_async and shutdown_async, which run that core on the tokio blocking pool so async callers never stall their executor.

Structs§

BlkTrace
Entry point for starting a trace.
BlkTraceEvent
One parsed trace record, normalized across the v1 and v2 record formats, together with its trailing pdu data.
BlkTraceReport
The outcome of a completed tracing session.
BlkTraceSession
A live tracing session.

Enums§

BlkIoKind
The kind of I/O a trace event represents.
BlktraceError
Errors returned by this crate.