:man| Alphabetical   Categories   About us 
PMCSTAT (8) | System administration commands and daemons | Unix Manual Pages | :man


pmcstat - "performance measurement with performance monitoring hardware"


See Also


pmcstat [-C] [-D pathname] [-E] [-O logfilename] [-P event-spec] [-R logfilename] [-S event-spec] [-W] [-c cpu] [-d] [-g] [-k kernelfile] [-n rate] [-o outputfile] [-p event-spec] [-s event-spec] [-t pid] [-w secs] [command [args]]


The pmcstat utility measures system performance using the facilities provided by hwpmc(4).

The pmcstat utility can measure both hardware events seen by the system as a whole, and those seen when a specified process is executing on the system’s CPUs. If a specific process is being targeted (for example, if the -t pid option is specified, or if a command line is specified using command), then measurement occurs till the target process exits or the pmcstat utility is interrupted by the user. If a specific process is not targeted for measurement, then pmcstat will perform system-wide measurements till interrupted by the user.

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


The following options are available:
-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 to enable per-process tracking.
-O logfilename
Send logging output to file logfilename. If this option 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.
-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.
-c cpu Set the cpu for subsequent system mode PMCs specified on the command line to cpu. The default is to allocate system mode PMCs on CPU zero.
-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.
-g Produce flat execution 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.
-k kernelfile
Set the pathname of the kernel to argument kernelfile. The default is /boot/kernel/kernel.
-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.
-p event-spec
Allocate a process mode counting PMC measuring hardware events specified in event-spec.
-s event-spec
Allocate a system mode counting PMC measuring hardware events specified in event-spec.
-t pid Attach all process mode PMCs allocated to the process with PID pid. The option is not allowed in conjunction with specifying a command using command.
-w secs
Print the values of all counting mode PMCs every secs seconds. The argument secs may be a fractional value. The default interval is 5 seconds.

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


To perform system-wide statistical sampling on an AMD Athlon CPU with samples taken every 32768 instruction retirals and data being sampled to file sample.stat, use:

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

To execute mozilla and measure the number of data cache misses suffered by it and its children every 12 seconds on an AMD Athlon, use:

"pmcstat -d -w 12 -p k7-dc-misses mozilla"

To collect a system-wide samples driven by processor instructions executed use:

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

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

"pmcstat -R /tmp/sample.out -g"


.Ex -std


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



Created by Blin Media, 2008-2013