perf-event: a Rust interface to Linux performance monitoring

This crate is a wrapper around the Linux perf_event_open API. It allows you to access a wide variety of the performance monitoring counters that are available in Linux.

This crate is a fork of Jim Blandy's perf-event crate that has been updated to support more features of the perf_event_open API.

Getting Started

Add the following to your Cargo.toml toml perf-event2 = "0.5"

Use Builder to create a perf counter, then use enable and disable to stop and start countinng. Call read to get your count. If you need to use multiple counters at once you can use Group. If you want to sample events from the kernel, check out Sampler.

Examples

For example, this counts the number of cycles used by the call to println!. Try adjusting the length of the vector to see the cycle count change.

```rust use perfevent::Builder; use perfevent::events::Hardware;

fn main() -> std::io::Result<()> { let mut counter = Builder::new(Hardware::INSTRUCTIONS).build()?;

let vec = (0..=51).collect::<Vec<_>>();

counter.enable()?;
println!("{:?}", vec);
counter.disable()?;

println!("{} instructions retired", counter.read()?);

Ok(())

} ```

The examples directory includes programs that count other sorts of events.

Differences between perf-event2 and perf-event

perf-event2 supports all the same features that perf-event does but it also supports the following: - All counter options introduced up to linux kernel 6.0. - Creating a Group to monitor anything other than all threads in the current process. - Sampled events via the kernel (e.g. gathering stack traces, etc.). Parsing the records emitted by the kernel is still not supported by this crate. - Direct access to the underlying perf_event_attr struct exposed by the kernel.

Migrating From perf-event

perf-event2 v0.4.8 is exactly the same as perf-event v0.4.8. You should be to just replace perf-event -> perf_event2 in your Cargo.toml and continue going with no changes. To get the new features, however, you will need to upgrade to v0.5.

The main change to be aware of is that Builder::new now takes an event directly. Where you would previously do this rust,ignore let counter = Builder::new() .kind(some_event) // ... .build()? you will now need to do this instead rust,ignore let counter = Builder::new(some_event) // ... .build()?; Note that if you didn't call kind the default event type was Hardware::INSTRUCTIONS.

See also