System Administration Commands cpustat(1M)
NAME
cpustat - monitor system behavior using CPU performance
counters
SYNOPSIS
cpustat -c eventspec [-c eventspec]... [-p period] [-sntD]
[interval [count]
cpustat -h
DESCRIPTION
The cpustat utility allows CPU performance counters to be
used to monitor the overall behavior of the CPUs in the sys-
tem.
If interval is specified, cpustat samples activity every
interval seconds, repeating forever. If a count is speci-
fied, 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 per-
formance 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 hexade-
cimal, octal, or decimal notation, in a for-
mat 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
SunOS 5.11 Last change: 18 Jul 2005 1
System Administration Commands cpustat(1M)
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.
-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 inter-
val, 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.
-n Omits all header output (useful if cpustat
is the beginning of a pipeline).
-t Prints an additional column of processor
cycle counts, if available on the current
architecture.
SunOS 5.11 Last change: 18 Jul 2005 2
System Administration Commands cpustat(1M)
USAGE
A closely related utility, cputrack(1), can be used to moni-
tor 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 perfor-
mance 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 set-
tings 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 implemen-
tation restrictions, overflows can be lost unless the sam-
pling 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 sam-
ples.
The output of cpustat is designed to be readily parseable 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 accessi-
ble to it in the current processor set. Thus, several
instances of the utility can be running on the CPUs in
SunOS 5.11 Last change: 18 Jul 2005 3
System Administration Commands cpustat(1M)
different processor sets. See psrset(1M) for more informa-
tion 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 ECref,ECmisses 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 Pen-
tium 4 machine.
example% cpustat -c \
pic12=branchretired,emask12=0x4,pic14=branchretired,\
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
SunOS 5.11 Last change: 18 Jul 2005 4
System Administration Commands cpustat(1M)
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=NBmemctrlrpageaccess,umask0=0x01, \
pic1=NBmemctrlrpageaccess,umask1=0x02, \
pic2=NBmemctrlrpageaccess,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 cpcopen() has failed and is
documented in cpcopen(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.
SunOS 5.11 Last change: 18 Jul 2005 5
System Administration Commands cpustat(1M)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcpcu
Interface Stability Evolving
SEE ALSO
cputrack(1), nawk(1), perl(1), iostat(1M), prstat(1M),
psrset(1M), vmstat(1M), cpc(3CPC), cpcopen(3CPC),
cpcbindcpu(3CPC), gethrtime(3C), strtoll(3C),
libcpc(3LIB), attributes(5)
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 cpcbindcpu(3CPC).
SunOS 5.11 Last change: 18 Jul 2005 6
|
