The
utility measures system performance using the facilities provided by
hwpmc(4).
The
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
utility is interrupted by the user.
If a specific set of processes is not targeted for measurement, then
will perform system-wide measurements till interrupted by the
user.
A given invocation of
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
.
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
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:
-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.
-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.
-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
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
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-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 CPUs.
The default is to allocate system mode PMCs on all 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.
-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 kerneldir
Set the pathname of the kernel directory to argument
kerneldir
This directory specifies where
should look for the kernel and its modules.
The default is
/boot/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
-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 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).
EXAMPLES
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:
