2 .\" Copyright (c) 2005, Sun Microsystems, Inc.
3 .TH CPUSTAT 1M "Jun 16, 2009"
5 cpustat \- monitor system behavior using CPU performance counters
9 \fBcpustat\fR \fB-c\fR \fIeventspec\fR [\fB-c\fR \fIeventspec\fR]... [\fB-p\fR \fIperiod\fR] [\fB-T\fR u | d ]
10 [\fB-sntD\fR] [\fIinterval\fR [\fIcount\fR]]
15 \fBcpustat\fR \fB-h\fR
21 The \fBcpustat\fR utility allows \fBCPU\fR performance counters to be used to
22 monitor the overall behavior of the \fBCPU\fRs in the system.
25 If \fIinterval\fR is specified, \fBcpustat\fR samples activity every
26 \fIinterval\fR seconds, repeating forever. If a \fIcount\fR is specified, the
27 statistics are repeated \fIcount\fR times. If neither are specified, an
28 interval of five seconds is used, and there is no limit to the number of
29 samples that are taken.
33 The following options are supported:
37 \fB\fB-c\fR \fIeventspec\fR\fR
41 Specifies a set of events for the \fBCPU\fR performance counters to monitor.
42 The syntax of these event specifications is:
46 [picn=]\fIeventn\fR[,attr[\fIn\fR][=\fIval\fR]][,[picn=]\fIeventn\fR
47 [,attr[n][=\fIval\fR]],...,]
52 You can use the \fB-h\fR option to obtain a list of available events and
53 attributes. This causes generation of the usage message. You can omit an
54 explicit counter assignment, in which case \fBcpustat\fR attempts to choose a
55 capable counter automatically.
57 Attribute values can be expressed in hexadecimal, octal, or decimal notation,
58 in a format suitable for \fBstrtoll\fR(3C). An attribute present in the event
59 specification without an explicit value receives a default value of \fB1\fR. An
60 attribute without a corresponding counter number is applied to all counters in
63 The semantics of these event specifications can be determined by reading the
64 \fBCPU\fR manufacturer's documentation for the events.
66 Multiple \fB-c\fR options can be specified, in which case the command cycles
67 between the different event settings on each sample.
87 Prints an extensive help message on how to use the utility and how to program
88 the processor-dependent counters.
98 Omits all header output (useful if \fBcpustat\fR is the beginning of a
105 \fB\fB-p\fR \fIperiod\fR\fR
109 Causes \fBcpustat\fR to cycle through the list of \fIeventspec\fRs every
110 \fIperiod\fR seconds. The tool sleeps after each cycle until \fIperiod\fR
111 seconds have elapsed since the first \fIeventspec\fR was measured.
113 When this option is present, the optional \fIcount\fR parameter specifies the
114 number of total cycles to make (instead of the number of total samples to
115 take). If \fIperiod\fR is less than the number of \fIeventspec\fRs times
116 \fIinterval\fR, the tool acts as it period is \fB0\fR.
126 Creates an idle soaker thread to spin while system-only \fIeventspec\fRs are
127 bound. One idle soaker thread is bound to each CPU in the current processor
128 set. System-only \fIeventspec\fRs contain both the \fBnouser\fR and the
129 \fBsys\fR tokens and measure events that occur while the CPU is operating in
130 privileged mode. This option prevents the kernel's idle loop from running and
131 triggering system-mode events.
137 \fB\fB-T\fR \fBu\fR | \fBd\fR\fR
141 Display a time stamp.
143 Specify \fBu\fR for a printed representation of the internal representation of
144 time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
155 Prints an additional column of processor cycle counts, if available on the
156 current architecture.
162 A closely related utility, \fBcputrack\fR(1), can be used to monitor the
163 behavior of individual applications with little or no interference from other
164 activities on the system.
167 The \fBcpustat\fR utility must be run by the super-user, as there is an
168 intrinsic conflict between the use of the \fBCPU\fR performance counters
169 system-wide by \fBcpustat\fR and the use of the \fBCPU\fR performance counters
170 to monitor an individual process (for example, by \fBcputrack\fR.)
173 Once any instance of this utility has started, no further per-process or
174 per-\fBLWP\fR use of the counters is allowed until the last instance of the
178 The times printed by the command correspond to the wallclock time when the
179 hardware counters were actually sampled, instead of when the program told the
180 kernel to sample them. The time is derived from the same timebase as
184 The processor cycle counts enabled by the \fB-t\fR option always apply to both
185 user and system modes, regardless of the settings applied to the performance
189 On some hardware platforms running in system mode using the "sys" token, the
190 counters are implemented using 32-bit registers. While the kernel attempts to
191 catch all overflows to synthesize 64-bit counters, because of hardware
192 implementation restrictions, overflows can be lost unless the sampling interval
193 is kept short enough. The events most prone to wrap are those that count
194 processor clock cycles. If such an event is of interest, sampling should occur
195 frequently so that less than 4 billion clock cycles can occur between samples.
198 The output of cpustat is designed to be readily parseable by \fBnawk\fR(1) and
199 \fBperl\fR(1), thereby allowing performance tools to be composed by embedding
200 \fBcpustat\fR in scripts. Alternatively, tools can be constructed directly
201 using the same \fBAPI\fRs that \fBcpustat\fR is built upon using the facilities
202 of \fBlibcpc\fR(3LIB). See \fBcpc\fR(3CPC).
205 The \fBcpustat\fR utility only monitors the \fBCPU\fRs that are accessible to
206 it in the current processor set. Thus, several instances of the utility can be
207 running on the \fBCPU\fRs in different processor sets. See \fBpsrset\fR(1M) for
208 more information about processor sets.
211 Because \fBcpustat\fR uses \fBLWP\fRs bound to \fBCPU\fRs, the utility might
212 have to be terminated before the configuration of the relevant processor can be
217 \fBExample 1 \fRMeasuring External Cache References and Misses
220 The following example measures misses and references in the external cache.
221 These occur while the processor is operating in user mode on an UltraSPARC
227 example% cpustat -c EC_ref,EC_misses 1 3
229 time cpu event pic0 pic1
230 1.008 0 tick 69284 1647
231 1.008 1 tick 43284 1175
232 2.008 0 tick 179576 1834
233 2.008 1 tick 202022 12046
234 3.008 0 tick 93262 384
235 3.008 1 tick 63649 1118
236 3.008 2 total 651077 18204
243 \fBExample 2 \fRMeasuring Branch Prediction Success on Pentium 4
246 The following example measures branch mispredictions and total branch
247 instructions in user and system mode on a Pentium 4 machine.
252 example% cpustat -c \e
253 pic12=branch_retired,emask12=0x4,pic14=branch_retired,\e
256 time cpu event pic12 pic14
263 3.010 2 total 2063 3101
269 \fBExample 3 \fRCounting Memory Accesses on Opteron
272 The following example determines the number of memory accesses made through
273 each memory controller on an Opteron, broken down by internal memory latency:
279 pic0=NB_mem_ctrlr_page_access,umask0=0x01, \e
280 pic1=NB_mem_ctrlr_page_access,umask1=0x02, \e
281 pic2=NB_mem_ctrlr_page_access,umask2=0x04,sys \e
284 time cpu event pic0 pic1 pic2
285 1.003 0 tick 41976 53519 7720
286 1.003 1 tick 5589 19402 731
287 2.003 1 tick 6011 17005 658
288 2.003 0 tick 43944 45473 7338
289 3.003 1 tick 7105 20177 762
290 3.003 0 tick 47045 48025 7119
291 4.003 0 tick 43224 46296 6694
292 4.003 1 tick 5366 19114 652
300 By running the \fBcpustat\fR command, the super-user forcibly invalidates all
301 existing performance counter context. This can in turn cause all invocations of
302 the \fBcputrack\fR command, and other users of performance counter context, to
303 exit prematurely with unspecified errors.
306 If \fBcpustat\fR is invoked on a system that has \fBCPU\fR performance counters
307 which are not supported by Solaris, the following message appears:
311 cpustat: cannot access performance counters - Operation not applicable
318 This error message implies that \fBcpc_open()\fR has failed and is documented
319 in \fBcpc_open\fR(3CPC). Review this documentation for more information about
320 the problem and possible solutions.
323 If a short interval is requested, \fBcpustat\fR might not be able to keep up
324 with the desired sample rate. In this case, some samples might be dropped.
328 See \fBattributes\fR(5) for descriptions of the following attributes:
336 ATTRIBUTE TYPE ATTRIBUTE VALUE
338 Interface Stability Evolving
344 \fBcputrack\fR(1), \fBnawk\fR(1), \fBperl\fR(1), \fBiostat\fR(1M),
345 \fBprstat\fR(1M), \fBpsrset\fR(1M), \fBvmstat\fR(1M), \fBcpc\fR(3CPC),
346 \fBcpc_open\fR(3CPC), \fBcpc_bind_cpu\fR(3CPC), \fBgethrtime\fR(3C),
347 \fBstrtoll\fR(3C), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
351 When \fBcpustat\fR is run on a Pentium 4 with HyperThreading enabled, a CPC set
352 is bound to only one logical CPU of each physical CPU. See
353 \fBcpc_bind_cpu\fR(3CPC).