Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PMCSTAT(8)              FreeBSD System Manager's Manual             PMCSTAT(8)

     pmcstat - performance measurement with performance monitoring hardware

     pmcstat [-C] [-D pathname] [-E] [-F pathname] [-G pathname]
             [-M mapfilename] [-N] [-O logfilename] [-P event-spec]
             [-R logfilename] [-S event-spec] [-T] [-W] [-c cpu-spec] [-d]
             [-f pluginopt] [-g] [-k kerneldir] [-m pathname] [-n rate]
             [-o outputfile] [-p event-spec] [-q] [-r fsroot] [-s event-spec]
             [-t process-spec] [-v] [-w secs] [-z graphdepth] [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 set of processes are
     executing on the system's CPUs.  If a specific set of processes is being
     targeted (for example, if the -t process-spec option is specified, or if
     a command line is specified using command), then measurement occurs till
     command exits, or till all target processes specified by the -t
     process-spec options exit, or till the pmcstat utility is interrupted by
     the user.  If a specific set of processes 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

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

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

     -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

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

             If the -O 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.

     -T      Use a top like mode for sampling PMCs. The following hotkeys can
             be used: 'c+a' switch to accumulative mode, 'c+d' switch to delta
             mode, 'm' merge PMCs, 'n' change view, 'p' show next PMC, ' '
             pause, 'q' quit. calltree only: 'f' cost under threshold is seen
             as a dot.

     -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

     -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 unhalted
             CPUs.  The default is to allocate system mode PMCs on all
             unhalted 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.

     -f pluginopt
             Pass option string to the active plugin.
             threshold=<float> do not display cost under specified value
             skiplink=0|1 replace node with cost under threshold by a dot

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

     -k kerneldir
             Set the pathname of the kernel directory to argument kerneldir.
             This directory specifies where pmcstat should look for the kernel
             and its modules.  The default is /boot/kernel.

     -m pathname
             Print the sampled PCs with the name, the start and ending
             addresses of the function within they live.  The pathname
             argument is mandatory and indicates where informations will be
             stored.  If argument pathname is a ``-'' this information is sent
             to the output file specified by 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

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

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

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

     To measure instructions retired for all processes named ``emacs'' use:
           pmcstat -t '^emacs$' -p instructions

     To measure instructions retired for processes named ``emacs'' for a
     period of 10 seconds use:
           pmcstat -t '^emacs$' -p instructions sleep 10

     To count instruction tlb-misses on CPUs 0 and 2 on a Intel Pentium
     Pro/Pentium III SMP system use:
           pmcstat -c 0,2 -s p6-itlb-miss

     To collect profiling information for a specific process with pid 1234
     based on instruction cache misses seen by it use:
           pmcstat -P ic-misses -t 1234 -O /tmp/sample.out

     To perform system-wide sampling on all configured processors based on
     processor instructions retired use:
           pmcstat -S instructions -O /tmp/sample.out
     If callgraph capture is not desired 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
     On the 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

     To print a system-wide profile with callgraphs to file foo.graph use:
           pmcstat -R /tmp/sample.out -G foo.graph

     If option -v is specified, pmcstat may issue the following diagnostic

     #callchain/dubious-frames  The number of callchain records that had an
     ``impossible'' value for a return address.

     #exec handling errors  The number of exec(2) events in the log file that
     named executables that could not be analyzed.

     #exec/elf  The number of exec(2) events that named ELF executables.

     #exec/unknown  The number of exec(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).

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

     Due to 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.  The generated gmon.out files are
     also only meaningful for native executables.

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

     The pmcstat utility first appeared in FreeBSD 6.0.  It is currently under

     Joseph Koshy <>

     The pmcstat utility cannot yet analyse hwpmc(4) logs generated by non-
     native architectures.

     On some versions of FreeBSD 7 data collection fails to work correctly if
     argument command is specified using a relative path name.  A suggested
     work-around is to specify command using an absolute pathname.

FreeBSD 11.0-PRERELEASE       September 19, 2008       FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help