[][src]Crate perf_event

A performance monitoring API for Linux.

This crate provides access to processor and kernel counters for things like instruction completions, cache references and misses, branch predictions, context switches, page faults, and so on.

For example, to compare the number of clock cycles elapsed with the number of instructions completed during one call to println!:

use perf_event::{Builder, Group};
use perf_event::events::Hardware;

fn main() -> std::io::Result<()> {
    // A `Group` lets us enable and disable several counters atomically.
    let mut group = Group::new()?;
    let cycles = Builder::new().group(&group).kind(Hardware::CPU_CYCLES).build()?;
    let insns = Builder::new().group(&group).kind(Hardware::INSTRUCTIONS).build()?;

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

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

    let counts = group.read()?;
    println!("cycles / instructions: {} / {} ({:.2} cpi)",
             counts[&cycles],
             counts[&insns],
             (counts[&cycles] as f64 / counts[&insns] as f64));

    Ok(())
}

This crate is built on top of the Linux perf_event_open system call; that documentation has the authoritative explanations of exactly what all the counters mean.

There are two main types for measurement:

  • A Counter is an individual counter. Use Builder to construct one.

  • A Group is a collection of counters that can be enabled and disabled atomically, so that they cover exactly the same period of execution, allowing meaningful comparisons of the individual values.

Call for PRs

Linux's perf_event_open API can report all sorts of things this crate doesn't yet understand: stack traces, logs of executable and shared library activity, tracepoints, kprobes, uprobes, and so on. And beyond the counters in the kernel header files, there are others that can only found at runtime by consulting sysfs, specific to particular processors and devices. For example, modern Intel processors have counters that measure power consumption in Joules.

If you find yourself in need of something this crate doesn't support, please consider submitting a pull request. (We intend to steadily raise our standards for testing and documentation, to ensure that technical contributions can have enough impact on users to justify the cost of inclusion, so be forewarned.)

Modules

events

Events we can monitor or count.

Structs

Builder

A builder for Counters.

Counter

A counter for one kind of kernel or hardware event.

Counts

A collection of counts from a Group of counters.

CountsIter

An iterator over the counter values in a Counts, returned by Group::read.

Group

A group of counters that can be managed as a unit.