PMCSTAT(8)

🦋 pmcstat(8) 🦋

okay bestie, this is the System Manager's Manual page for performance measurement with performance monitoring hardware, and it's lowkey iconic. no cap, it's giving "your CPU is a main character and I have receipts." 💅

🌸 NAME 🌸

pmcstat — performance measurement with performance monitoring hardware

✨ SYNOPSIS ✨

pmcstat [-A] [-C] [-D pathname] [-E] [-F pathname] [-G pathname] [-I]
        [-L] [-M mapfilename] [-N] [-O logfilename] [-P event-spec]
        [-R logfilename] [-S event-spec] [-T] [-U] [-W] [-a pathname]
        [-c cpu-spec] [-d] [-e] [-f pluginopt] [-g] [-i lwp] [-l secs]
        [-m pathname] [-n rate] [-o outputfile] [-p event-spec] [-q]
        [-r fsroot] [-s event-spec] [-t process-spec] [-u event-spec]
        [-v] [-w secs] [-z graphdepth] [command [args]]

💅 DESCRIPTION 💅

okay so pmcstat measures system performance using the facilities provided by hwpmc(4). it can measure both hardware events seen by the system as a whole and those seen when a specified set of processes are executing on the system's CPUs.

if you're targeting a specific set of processes (for example, you passed -t process-spec, or you specified a command line using command), then measurement happens until command exits, or until all the target processes specified by the -t process-spec options exit, or until the user interrupts pmcstat. if you're not targeting a specific set of processes, pmcstat does system-wide measurements until the user interrupts it. 😌

a given invocation of pmcstat can mix allocations of system-mode and process-mode PMCs, of both counting and sampling flavors. the values of all counting PMCs are printed in human readable form at regular intervals by pmcstat. the format of pmcstat's human-readable textual output is not stable, and could change in the future — so don't get too attached to parsing it, bestie. the output of sampling PMCs may be configured to go to a log file for subsequent offline analysis, or — at the expense of greater overhead — may be configured to be printed in text form on the fly.

hardware events to measure are specified to pmcstat using event specifier strings event-spec. the syntax of these event specifiers is machine dependent and is documented in pmc(3).

a process-mode PMC may be configured to be inheritable by the target process' current and future children.

🎀 OPTIONS 🎀

the following options are available:

• -A — skip symbol lookup and display address instead.
• -C — toggle between showing cumulative or incremental counts for subsequent counting mode PMCs specified on the command line. the default is to show incremental counts.
• -D pathname — create files with per-program samples in the directory named by pathname. the default is to create these files in the current directory.
• -E — toggle showing per-process counts at the time a tracked process exits for subsequent process-mode PMCs specified on the command line. this option is useful for mapping the performance characteristics of a complex pipeline of processes when used in conjunction with the -d option. the default is to not enable per-process tracking.
• -F pathname — print calltree (Kcachegrind) information to file pathname. if argument pathname is a -, this information is sent to the output file specified by the -o option.
• -G pathname — print callchain information to file pathname. if argument pathname is a -, this information is sent to the output file specified by the -o option.
• -I — show the offset of the instruction pointer into the symbol.
• -L — list all event names.
• -M mapfilename — write the mapping between executable objects encountered in the event log and the abbreviated pathnames used for gprof(1) profiles to file mapfilename. if this option is not specified, mapping information is not written. argument mapfilename may be a -, in which case this mapping information is sent to the output file configured by the -o option.
• -N — toggle capturing callchain information for subsequent sampling PMCs. the default is for sampling PMCs to capture callchain information.
• -O logfilename — send logging output to file logfilename. if logfilename is of the form hostname:port, where hostname does not start with a . or a /, then pmcstat will open a network socket to host hostname on port port. also, if -O is not specified and one of the logging options is requested, then pmcstat will print a textual form of the logged events to the configured output file.
• -P event-spec — allocate a process mode sampling PMC measuring hardware events specified in event-spec.
• -R logfilename — perform offline analysis using sampling data in file logfilename.
• -S event-spec — allocate a system mode sampling PMC measuring hardware events specified in event-spec.
• -T — use a top(1)-like mode for sampling PMCs. the following hotkeys can be used:
  • A — toggle symbol resolution
  • Ctrl+a — switch to accumulative mode
  • Ctrl+d — switch to delta mode
  • f — represent the “f” cost under threshold as a dot (calltree only)
  • I — toggle showing offsets into symbols
  • m — merge PMCs
  • n — change view
  • p — show next PMC
  • q — quit
  • Space — pause
• -U — toggle capturing user-space call traces while in kernel mode. the default is for sampling PMCs to capture user-space callchain information while in user-space mode, and kernel callchain information while in kernel mode.
• -W — toggle logging the incremental counts seen by the threads of a tracked process each time they are scheduled on a CPU. this is an experimental feature intended to help analyse the dynamic behaviour of processes in the system. it may incur substantial overhead if enabled. the default is for this feature to be disabled.
• -a pathname — perform a symbol and file:line lookup for each address in each callgraph and save the output to pathname. unlike -m, which only resolves the first symbol in the graph, this resolves every node in the callgraph, or prints out addresses if no lookup information is available. this option requires the -R option to read in samples that were previously collected and saved with the -O option.
• -c cpu-spec — set the cpus for subsequent system mode PMCs specified on the command line to cpu-spec. argument cpu-spec is a comma separated list of CPU numbers, or the literal * denoting all available CPUs. the default is to allocate system mode PMCs on all available CPUs.
• -d — toggle between process mode PMCs measuring events for the target process' current and future children or only measuring events for the target process. the default is to measure events for the target process alone. (it has to be passed in the command line prior to -p, -s, -P, or -S).
• -e — specify that the gprof profile files will use a wide history counter. these files are produced in a format compatible with gprof(1). however, other tools that cannot fully parse a BSD-style gmon header might be unable to correctly parse these files.
• -f pluginopt — pass option string to the active plugin.
  • threshold=<float> — do not display cost under specified value (Top).
  • skiplink=0|1 — replace node with cost under threshold by a dot (Top).
• -g — produce profiles in a format compatible with gprof(1). a separate profile file is generated for each executable object encountered. profile files are placed in sub-directories named by their PMC event name.
• -i lwp — filter on thread ID lwp, which you can get from ps(1) -o lwp.
• -l secs — set system-wide performance measurement duration for secs seconds. the argument secs may be a fractional value.
• -m pathname — print the sampled PCs with the name, the start and ending addresses of the function they live in. the pathname argument is mandatory and indicates where the information will be stored. if argument pathname is a -, this information is sent to the output file specified by the -o option. this option requires the -R option to read in samples that were previously collected and saved with the -O option.
• -n rate — set the default sampling rate for subsequent sampling mode PMCs specified on the command line. the default is to configure PMCs to sample the CPU's instruction pointer every 65536 events.
• -o outputfile — send counter readings and textual representations of logged data to file outputfile. the default is to send output to stderr when collecting live data and to stdout when processing a pre-existing logfile.
• -p event-spec — allocate a process mode counting PMC measuring hardware events specified in event-spec.
• -q — decrease verbosity.
• -r fsroot — set the top of the filesystem hierarchy under which executables are located to argument fsroot. the default is /.
• -s event-spec — allocate a system mode counting PMC measuring hardware events specified in event-spec.
• -t process-spec — attach process mode PMCs to the processes named by argument process-spec. argument process-spec may be a non-negative integer denoting a specific process id, or a regular expression for selecting processes based on their command names.
• -u event-spec — provide short description of event.
• -v — increase verbosity.
• -w secs — print the values of all counting mode PMCs or sampling mode PMCs for top mode every secs seconds. the argument secs may be a fractional value. the default interval is 5 seconds.
• -z graphdepth — when printing system-wide callgraphs, limit callgraphs to the depth specified by argument graphdepth.

if command is specified, it is executed using execvp(3).

🎀 EXAMPLES 🎀

Ok bestie, this is the part where it all clicks. These are the copy-paste-and-go recipes, and honestly? They're giving tutorial energy. 💅

To do a system-wide statistical sampling on an AMD Athlon CPU, with samples taken every 32768 instruction retirals, and the data dumped into the file sample.stat, you'd say:

pmcstat -O sample.stat -n 32768 -S k7-retired-instructions

To run firefox and measure how many data cache misses it (and its children, the little nepo babies) suffer through every 12 seconds, on an AMD Athlon, use:

pmcstat -d -w 12 -p k7-dc-misses firefox

To measure instructions retired for all processes named “emacs”, do:

pmcstat -t '^emacs$' -p instructions

Same energy, but only for a period of 10 seconds? Easy:

pmcstat -t '^emacs$' -p instructions sleep 10

To count instruction tlb-misses on CPUs 0 and 2 on an Intel Pentium Pro/Pentium III SMP system, use:

pmcstat -c 0,2 -s p6-itlb-miss

To collect profiling info for one specific process, pid 1234, based on the instruction cache misses it's been seeing, use:

pmcstat -P ic-misses -t 1234 -O /tmp/sample.out

To do system-wide sampling across all configured processors, based on processor instructions retired, use:

pmcstat -S instructions -O /tmp/sample.out

And if callgraph capture is not the vibe for you, use:

pmcstat -N -S instructions -O /tmp/sample.out

To send the generated event log to a remote machine, use:

pmcstat -S instructions -O remotehost:port

Then on that remote machine, the sample log can be collected using nc(1):

nc -l remotehost port > /tmp/sample.out

To generate gprof(1)-compatible profiles from a sample file, use:

pmcstat -R /tmp/sample.out -g

And to print a system-wide profile with callgraphs out to the file foo.graph, use:

pmcstat -R /tmp/sample.out -G foo.graph

---

💀 DIAGNOSTICS 💀

If the option -v is specified, pmcstat may issue the following diagnostic messages — think of these as the receipts it hands you back. 🧾

• #callchain/dubious-frames — the number of callchain records that had an “impossible” value for a return address. Like, ma'am, that address cannot exist. 🙈
• #exec handling errors — the number of execve(2) events in the log file that named executables which could not be analyzed.
• #exec/elf — the number of execve(2) events that named ELF executables.
• #exec/unknown — the number of execve(2) events that named executables with unrecognized formats.
• #samples/total — the total number of samples in the log file.
• #samples/unclaimed — the number of samples that could not be correlated to a known executable object (i.e., to an executable, shared library, the kernel or the runtime loader). These are the samples that ghosted us. 😭
• #samples/unknown-object — the number of samples that were associated with an executable with an unrecognized object format.

The pmcstat utility exits 0 on success, and >0 if an error occurs. Periodt. ✨

---

🌈 COMPATIBILITY 🌈

Real talk, there are some limits here. Because of the limitations of the gmon.out file format, gprof(1)-compatible profiles generated by the -g option do not contain information about calls that cross executable boundaries. Also, the generated gmon.out files are only meaningful for native executables. No cap, that's just how it is.

---

🦋 SEE ALSO 🦋

gprof(1), nc(1), execvp(3), pmc(3), pmclog(3), hwpmc(4), pmccontrol(8), sysctl(8)

Go read them, bestie. iykyk. 💅

---

⭐ HISTORY ⭐

The pmcstat utility first appeared in FreeBSD 6.0. Iconic behavior from day one, honestly. 👑

---

💖 AUTHORS 💖

Joseph Koshy <jkoshy@FreeBSD.org> — thank you for your service, king. 🫶

---

🍓 BUGS 🍓

The pmcstat utility cannot yet analyse hwpmc(4) logs generated by non-native architectures. She's doing her best, ok?? 😭

---

💅 That's the whole page, bestie — this Debian build is dated April 19, 2025, so go forth and profile like the main character you are. Stay slay, keep your callchains tidy, and remember: samples unclaimed are just samples that haven't found their people yet. ✨🎀🦋