Struct PerfFile

pub struct PerfFile { /* private fields */ }

Contains the information from the perf.data file header and feature sections.

Implementations

impl PerfFile

pub fn event_attributes(&self) -> &[AttributeDescription]

The attributes which were requested for each perf event, along with the IDs.

pub fn build_ids(&self) -> Result<HashMap<DsoKey, DsoInfo>, Error>

Returns a map of build ID entries. perf record creates these records for any DSOs which it thinks have been “hit” in the profile. They supplement Mmap records, which usually don’t come with build IDs.

This method returns a HashMap so that you can easily look up the right build ID from the DsoKey in an Mmap event. For some DSOs, the path in the raw Mmap event can be different from the path in the build ID record; for example, the Mmap event for the kernel (“vmlinux”) image could have the path “[kernel.kallsyms]_text”, whereas the corresponding build ID record might have the path “[kernel.kallsyms]” (without the trailing “_text”), or it could even have the full absolute path to a vmlinux file. The DsoKey canonicalizes those differences away.

Having the build ID for a DSO allows you to do the following:

• If the DSO file has changed in the time since the perf.data file was captured, you can detect this change because the new file will have a different build ID.
• If debug symbols are installed for the DSO, you can sometimes find the debug symbol file using the build ID. For example, you might find it at /usr/lib/debug/.build-id/b8/037b6260865346802321dd2256b8ad1d857e63.debug
• If the original DSO file is gone, or you’re trying to read the perf.data file on an entirely different machine, you can sometimes retrieve the original DSO file just from its build ID, for example from a debuginfod server.
• This also works for DSOs which are not present on the file system at all; specifically, the vDSO file is a bit of a pain to obtain. With the build ID you can instead obtain it from, say, https://debuginfod.elfutils.org/buildid/0d82ee4bd7f9609c367095ba0bedf155b71cb058/executable

This method is a bit lossy. We discard the pid, because it seems to be always -1 in the files I’ve tested. We also discard any entries for which we fail to create a DsoKey.

pub fn sample_time_range(&self) -> Result<Option<SampleTimeRange>, Error>

The timestamp of the first and the last sample in this file.

pub fn hostname(&self) -> Result<Option<&str>, Error>

The hostname where the data was collected (uname -n).

pub fn os_release(&self) -> Result<Option<&str>, Error>

The OS release where the data was collected (uname -r).

pub fn perf_version(&self) -> Result<Option<&str>, Error>

The perf user tool version where the data was collected. This is the same as the version of the Linux source tree the perf tool was built from.

pub fn arch(&self) -> Result<Option<&str>, Error>

The CPU architecture (uname -m).

pub fn nr_cpus(&self) -> Result<Option<NrCpus>, Error>

A structure defining the number of CPUs.

pub fn cpu_desc(&self) -> Result<Option<&str>, Error>

The description of the CPU. On x86 this is the model name from /proc/cpuinfo.

pub fn cpu_id(&self) -> Result<Option<&str>, Error>

The exact CPU type. On x86 this is vendor,family,model,stepping. For example: GenuineIntel,6,69,1

pub fn is_stats(&self) -> bool

If true, the data section contains data recorded from perf stat record.

pub fn cmdline(&self) -> Result<Option<Vec<&str>>, Error>

The perf arg-vector used to collect the data.

pub fn total_mem(&self) -> Result<Option<u64>, Error>

The total memory in kilobytes. (MemTotal from /proc/meminfo)

pub fn simpleperf_meta_info(&self) -> Result<Option<HashMap<&str, &str>>, Error>

The meta info map, if this is a Simpleperf profile.

pub fn simpleperf_symbol_tables( &self, ) -> Result<Option<Vec<SimpleperfFileRecord>>, Error>

Symbol tables from Simpleperf.

perf.data files from simpleperf come with a FILE2 section which contains, for each DSO that was hit by a stack frame, the symbol table from the file as present on the device.

pub fn pmu_mappings(&self) -> Result<Option<PmuMappings>, Error>

The names of the dynamic PMU types used in PerfEventType::DynamicPmu.

This mapping allows you to interpret the perf event type field of the perf event attributes returned by PerfFile::event_attributes.

For example, let’s say you observed a kprobe or a uprobe. The perf event will be of type DynamicPmu, and its dynamic PMU type ID might be 6 or 7.

Just by seeing this 6 or 7 you don’t know for sure what type of event it is. But the pmu_mappings() map will have a 6 => “kprobe” and a 7 => “uprobe” entry. Once you see those entries, you can be sure what you’re dealing with.

This map also contains the values “software”, “tracepoint”, and “breakpoint”; those always have the IDs 1, 2 and 5, respectively.

Additionally, the map contains the CPU-specific dynamic entries. For example, an Intel CPU might have IDs for the names “cpu”, “intel_bts”, “intel_pt”, “msr”, “uncore_imc”, “uncore_cbox_0”, …, “uncore_cbox_7”, “uncore_arb”, “cstate_core”, “cstate_pkg”, “power”, “i915”.

pub fn features(&self) -> FeatureSet

The set of features used in this perf file.

pub fn feature_section_data(&self, feature: Feature) -> Option<&[u8]>

The raw data of a feature section.

pub fn endian(&self) -> Endianness

The file endian.