Crate perf_event_data

Expand description

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.

Crate perf_event_dataCopy item path