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::events::Hardware;
use perf_event::{Builder, Group};

// A `Group` lets us enable and disable several counters atomically.
let mut group = Group::new()?;
let cycles = group.add(&Builder::new(Hardware::CPU_CYCLES))?;
let insns = group.add(&Builder::new(Hardware::INSTRUCTIONS))?;

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. You can construct one via Group::new or use Builder to construct one with custom settings.

If you’re familiar with the kernel API already:

• A Builder holds the arguments to a perf_event_open call: a struct perf_event_attr and a few other fields.

• Counter and Group objects are just event file descriptors, together with their kernel id numbers, and some other details you need to actually use them. They’re different types because they yield different types of results, and because you can’t retrieve a Group’s counts without knowing how many members it has.

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 be 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.

Modules

• data
  Support for parsing data contained within Records.
• events
  Events we can monitor or count.

Structs

• Builder
  A builder for Counters.
• Clock
  Supported linux clocks that can be used within a perf_event instance.
• CountAndTime
  The value of a counter, along with timesharing data.
• Counter
  A counter for a single kernel or hardware event.
• CounterData
  The data retrieved by reading from a Counter.
• Group
  A group of counters that can be managed as a unit.
• GroupData
  A collection of counts from a group of counters.
• GroupEntry
  Individual entry for a counter returned by Group::read.
• GroupIter
  Iterator over the entries contained within GroupData.
• ReadFormat
  Flags that control what data is returned when reading from a perf_event file descriptor.
• Record
  A view into a Sampler’s ring buffer for a single kernel event record.
• SampleBranchFlag
  Specify what branches to include in a branch record.
• SampleFlag
  Specifies which fields to include in the sample.
• Sampler
  A sampled perf event.
• UnsupportedOptionsError
  Attempted to build a counter using options that the current kernel does not support.
• UserReadData
  Data read from a call to Sampler::read_user.

Enums

• SampleSkid
  Configuration of how much skid is allowed when gathering samples.