CPUSTAT(8) Maintenance Procedures CPUSTAT(8)
NAME
cpustat - monitor system behavior using CPU performance counters
SYNOPSIS
cpustat -c eventspec [
-c eventspec]... [
-p period] [
-T u | d ]
[
-sntD] [
interval [
count]]
cpustat -hDESCRIPTION
The
cpustat utility allows
CPU performance counters to be used to monitor
the overall behavior of the
CPUs in the system.
If
interval is specified,
cpustat samples activity every
interval seconds, repeating forever. If a
count is specified, the statistics are
repeated
count times. If neither are specified, an interval of five
seconds is used, and there is no limit to the number of samples that are
taken.
OPTIONS
The following options are supported:
-c eventspec Specifies a set of events for the
CPU performance counters to
monitor. The syntax of these event specifications is:
[picn=]
eventn[,attr[
n][=
val]][,[picn=]
eventn [,attr[n][=
val]],...,]
You can use the
-h option to obtain a list of available events and
attributes. This causes generation of the usage message. You can omit
an explicit counter assignment, in which case
cpustat attempts to
choose a capable counter automatically.
Attribute values can be expressed in hexadecimal, octal, or decimal
notation, in a format suitable for
strtoll(3C). An attribute present
in the event specification without an explicit value receives a
default value of
1. An attribute without a corresponding counter
number is applied to all counters in the specification.
The semantics of these event specifications can be determined by
reading the
CPU manufacturer's documentation for the events.
Multiple
-c options can be specified, in which case the command
cycles between the different event settings on each sample.
-D Enables debug mode.
-h Prints an extensive help message on how to use the utility and how to
program the processor-dependent counters.
-n Omits all header output (useful if
cpustat is the beginning of a
pipeline).
-p period Causes
cpustat to cycle through the list of
eventspecs every
period seconds. The tool sleeps after each cycle until
period seconds have
elapsed since the first
eventspec was measured.
When this option is present, the optional
count parameter specifies
the number of total cycles to make (instead of the number of total
samples to take). If
period is less than the number of
eventspecs
times
interval, the tool acts as it period is
0.
-s Creates an idle soaker thread to spin while system-only
eventspecs
are bound. One idle soaker thread is bound to each CPU in the current
processor set. System-only
eventspecs contain both the
nouser and the
sys tokens and measure events that occur while the CPU is operating
in privileged mode. This option prevents the kernel's idle loop from
running and triggering system-mode events.
-T u |
d Display a time stamp.
Specify
u for a printed representation of the internal representation
of time. See
time(2). Specify
d for standard date format. See
date(1).
-t Prints an additional column of processor cycle counts, if available
on the current architecture.
USAGE
A closely related utility,
cputrack(1), can be used to monitor the
behavior of individual applications with little or no interference from
other activities on the system.
The
cpustat utility must be run by the super-user, as there is an
intrinsic conflict between the use of the
CPU performance counters
system-wide by
cpustat and the use of the
CPU performance counters to
monitor an individual process (for example, by
cputrack.)
Once any instance of this utility has started, no further per-process or
per-
LWP use of the counters is allowed until the last instance of the
utility terminates.
The times printed by the command correspond to the wallclock time when
the hardware counters were actually sampled, instead of when the program
told the kernel to sample them. The time is derived from the same
timebase as
gethrtime(3C).
The processor cycle counts enabled by the
-t option always apply to both
user and system modes, regardless of the settings applied to the
performance counter registers.
On some hardware platforms running in system mode using the "sys" token,
the counters are implemented using 32-bit registers. While the kernel
attempts to catch all overflows to synthesize 64-bit counters, because of
hardware implementation restrictions, overflows can be lost unless the
sampling interval is kept short enough. The events most prone to wrap are
those that count processor clock cycles. If such an event is of interest,
sampling should occur frequently so that less than 4 billion clock cycles
can occur between samples.
The output of cpustat is designed to be readily parsable by
nawk(1) and
perl(1), thereby allowing performance tools to be composed by embedding
cpustat in scripts. Alternatively, tools can be constructed directly
using the same
APIs that
cpustat is built upon using the facilities of
libcpc(3LIB). See
cpc(3CPC).
The
cpustat utility only monitors the
CPUs that are accessible to it in
the current processor set. Thus, several instances of the utility can be
running on the
CPUs in different processor sets. See
psrset(8) for more
information about processor sets.
Because
cpustat uses
LWPs bound to
CPUs, the utility might have to be
terminated before the configuration of the relevant processor can be
changed.
EXAMPLES
SPARC
Example 1: Measuring External Cache References and Misses
The following example measures misses and references in the external
cache. These occur while the processor is operating in user mode on an
UltraSPARC machine.
example% cpustat -c EC_ref,EC_misses 1 3
time cpu event pic0 pic1
1.008 0 tick 69284 1647
1.008 1 tick 43284 1175
2.008 0 tick 179576 1834
2.008 1 tick 202022 12046
3.008 0 tick 93262 384
3.008 1 tick 63649 1118
3.008 2 total 651077 18204
x86 Example 2: Measuring Branch Prediction Success on Pentium 4
The following example measures branch mispredictions and total branch
instructions in user and system mode on a Pentium 4 machine.
example% cpustat -c \
pic12=branch_retired,emask12=0x4,pic14=branch_retired,\
emask14=0xf,sys 1 3
time cpu event pic12 pic14
1.010 1 tick 458 684
1.010 0 tick 305 511
2.010 0 tick 181 269
2.010 1 tick 469 684
3.010 0 tick 182 269
3.010 1 tick 468 684
3.010 2 total 2063 3101
Example 3: Counting Memory Accesses on Opteron
The following example determines the number of memory accesses made
through each memory controller on an Opteron, broken down by internal
memory latency:
cpustat -c \
pic0=NB_mem_ctrlr_page_access,umask0=0x01, \
pic1=NB_mem_ctrlr_page_access,umask1=0x02, \
pic2=NB_mem_ctrlr_page_access,umask2=0x04,sys \
1
time cpu event pic0 pic1 pic2
1.003 0 tick 41976 53519 7720
1.003 1 tick 5589 19402 731
2.003 1 tick 6011 17005 658
2.003 0 tick 43944 45473 7338
3.003 1 tick 7105 20177 762
3.003 0 tick 47045 48025 7119
4.003 0 tick 43224 46296 6694
4.003 1 tick 5366 19114 652
WARNINGS
By running the
cpustat command, the super-user forcibly invalidates all
existing performance counter context. This can in turn cause all
invocations of the
cputrack command, and other users of performance
counter context, to exit prematurely with unspecified errors.
If
cpustat is invoked on a system that has
CPU performance counters which
are not supported by Solaris, the following message appears:
cpustat: cannot access performance counters - Operation not applicable
This error message implies that
cpc_open() has failed and is documented
in
cpc_open(3CPC). Review this documentation for more information about
the problem and possible solutions.
If a short interval is requested,
cpustat might not be able to keep up
with the desired sample rate. In this case, some samples might be
dropped.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
SEE ALSO
cputrack(1),
nawk(1),
perl(1),
gethrtime(3C),
strtoll(3C),
cpc(3CPC),
cpc_bind_cpu(3CPC),
cpc_open(3CPC),
libcpc(3LIB),
attributes(7),
iostat(8),
prstat(8),
psrset(8),
vmstat(8)NOTES
When
cpustat is run on a Pentium 4 with HyperThreading enabled, a CPC set
is bound to only one logical CPU of each physical CPU. See
cpc_bind_cpu(3CPC).
April 9, 2016
CPUSTAT(8)