Crate perf_event_data

Parse data emitted by the linux perf_event_open syscall.

Important Types

• Record is an enum that can parse any known record type emitted by perf_event_open. You will likely want to start here.
• The parse module has the Parser and ParseConfig types which you will need in order to parse anything.

Example

Parsing a mmap record directly from its raw byte format.

use perf_event_data::endian::Little;
use perf_event_data::parse::{ParseConfig, Parser};
use perf_event_data::Record;

let data: &[u8] = &[
    0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x00, 0x16, 0x4C, 0x01, 0x00, 0x17, 0x4C, 0x01,
    0x00, 0x00, 0xA0, 0x48, 0x96, 0x4F, 0x7F, 0x00, 0x00, 0x00, 0x10, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0xA0, 0x48, 0x96, 0x4F, 0x7F, 0x00, 0x00, 0x2F, 0x2F, 0x61, 0x6E, 0x6F,
    0x6E, 0x00, 0x00,
];

let config = ParseConfig::<Little>::default();
let mut parser = Parser::new(data, config);
let record: Record = parser.parse()?;

let mmap = match record {
    Record::Mmap(mmap) => mmap,
    _ => panic!("expected a MMAP record"),
};

Crate Orginization

This crate is organized like this:

• The root contains all the data types that records can be parsed into. This includes not only the types corresponding to the perf records but also those that make up their fields, and so on.
• The parse module contains types and traits needed to implement parsing support. Most types exposed in the root implement Parse but to actually make use of that you will need the Parser and ParseConfig types from the parse module.
• The endian module contains some types for converting values to the native endian. You likely won’t have to interact with it other than picking one type to use when creating a ParseConfig.

Parsing perf.data files

This crate doesn’t yet have support for this, although it could be used as part of implementing a larger parser. If you would like to do this please open an issue!

Modules

• endian
  Traits and types for converting between a source endianness and that of the current host.
• parse
  Parsing interface for parsing data in to record types.

Structs

• Aux
  AUX records indicate that new data is available in the aux buffer region.
• AuxFlags
  Flags describing the aux buffer update.
• AuxOutputHwId
  AUX_OUTPUT_HW_ID events allow matching data written to the aux area with an architecture-specific hadrware ID.
• AuxPmuFormatType
  PMU-specific trace format type
• BpfEvent
  BPF_EVENT records indicate when a BPF program is loaded or unloaded.
• BpfEventType
  Indicates the type of a BpfEvent
• BranchEntry
  Record of a branch taken by the hardware.
• BranchType
  Branch type as used by the last branch record.
• CGroup
  CGROUP records indicate when a new cgroup is created and activated.
• Comm
  COMM records indicate changes in process names.
• DataSource
  Describes where in the memory hierarchy the sampled instruction came from.
• Exit
  EXIT records indicate that a process has exited.
• GroupEntry
  The values read from a single perf event counter.
• GroupIter
  Iterator over the entries of a group.
• ITraceStart
  ITRACE_START records indicate when a process has started an instruction trace.
• KSymbol
  KSYMBOL records indicate symbols being registered or unregistered within the kernel.
• KSymbolFlags
  Flags for KSymbol.
• KSymbolType
  The type of the kernel symbol.
• Lost
  Lost records indicate when events are dropped by the kernel.
• LostSamples
  LOST_SAMPLES records indicate that some samples were lost while using hardware sampling.
• MemBlk
  Access was blocked.
• MemDtlb
  Memory TLB access.
• MemLevel
  Location in the memory hierarchy.
• MemLevelNum
  Memory hierarchy level number.
• MemLock
  Whether the instruction was a locked instruction.
• MemOp
  Memory operation.
• MemSnoop
  Memory snoop mode.
• MemSnoopX
  Extended bits for MemSnoop.
• Mmap
  MMAP events record memory mappings.
• Mmap2
  MMAP2 events record memory mappings with extra info compared to MMAP records.
• NamespaceEntry
  An individual namespace entry.
• Namespaces
  NAMESPACES records include namespace information of a process.
• Read
  READ events happen when the kernel records the counters on its own.
• ReadFormat
  Flags that control what data is returned when reading from a perf_event file descriptor.
• ReadGroup
  The values read from a group of counters.
• ReadValue
  Data read from a counter.
• RecordMetadata
  Extra record data emitted by the kernel that is common to all records.
• Registers
  Describes the captured subset of registers when a sample was taken.
• Sample
  A sample emitted by the kernel.
• SampleFlags
  Specifies which fields to include in the sample.
• SampleId
  A subset of the sample fields that can be recorded in non-SAMPLE records.
• SampleRegsAbi
  ABI of the program when sampling registers.
• TextPoke
  TEXT_POKE records indicate a change in the kernel text.
• Throttle
  Record for a throttle or unthrottle events.
• TryFromGroupError
  Error when attempting to convert ReadGroup to a ReadValue.
• Txn
  Info about a transactional memory event.

Enums

• Record
  A record emitted by the linux kernel.
• SwitchCpuWide
  SWITCH_CPU_WIDE records indicates a context switch when profiling in cpu-wide mode.

Traits

• Visitor
  A visitor for visiting parsed records.

Type Aliases

• Fork
  FORK records indicate that a process called fork(2) successfully.