1cpustat(1M) System Administration Commands cpustat(1M)
2
3
4
6 cpustat - monitor system behavior using CPU performance counters
7
9 cpustat -c eventspec [-c eventspec]... [-p period] [-T u | d ]
10 [-sntD] [interval [count]]
11
12
13 cpustat -h
14
15
17 The cpustat utility allows CPU performance counters to be used to moni‐
18 tor the overall behavior of the CPUs in the system.
19
20
21 If interval is specified, cpustat samples activity every interval sec‐
22 onds, repeating forever. If a count is specified, the statistics are
23 repeated count times. If neither are specified, an interval of five
24 seconds is used, and there is no limit to the number of samples that
25 are taken.
26
28 The following options are supported:
29
30 -c eventspec
31
32 Specifies a set of events for the CPU performance counters to moni‐
33 tor. The syntax of these event specifications is:
34
35 [picn=]eventn[,attr[n][=val]][,[picn=]eventn
36 [,attr[n][=val]],...,]
37
38
39 You can use the -h option to obtain a list of available events and
40 attributes. This causes generation of the usage message. You can
41 omit an explicit counter assignment, in which case cpustat attempts
42 to choose a capable counter automatically.
43
44 Attribute values can be expressed in hexadecimal, octal, or decimal
45 notation, in a format suitable for strtoll(3C). An attribute
46 present in the event specification without an explicit value
47 receives a default value of 1. An attribute without a corresponding
48 counter number is applied to all counters in the specification.
49
50 The semantics of these event specifications can be determined by
51 reading the CPU manufacturer's documentation for the events.
52
53 Multiple -c options can be specified, in which case the command
54 cycles between the different event settings on each sample.
55
56
57 -D
58
59 Enables debug mode.
60
61
62 -h
63
64 Prints an extensive help message on how to use the utility and how
65 to program the processor-dependent counters.
66
67
68 -n
69
70 Omits all header output (useful if cpustat is the beginning of a
71 pipeline).
72
73
74 -p period
75
76 Causes cpustat to cycle through the list of eventspecs every period
77 seconds. The tool sleeps after each cycle until period seconds have
78 elapsed since the first eventspec was measured.
79
80 When this option is present, the optional count parameter specifies
81 the number of total cycles to make (instead of the number of total
82 samples to take). If period is less than the number of eventspecs
83 times interval, the tool acts as it period is 0.
84
85
86 -s
87
88 Creates an idle soaker thread to spin while system-only eventspecs
89 are bound. One idle soaker thread is bound to each CPU in the cur‐
90 rent processor set. System-only eventspecs contain both the nouser
91 and the sys tokens and measure events that occur while the CPU is
92 operating in privileged mode. This option prevents the kernel's
93 idle loop from running and triggering system-mode events.
94
95
96 -T u | d
97
98 Display a time stamp.
99
100 Specify u for a printed representation of the internal representa‐
101 tion of time. See time(2). Specify d for standard date format. See
102 date(1).
103
104
105 -t
106
107 Prints an additional column of processor cycle counts, if available
108 on the current architecture.
109
110
112 A closely related utility, cputrack(1), can be used to monitor the
113 behavior of individual applications with little or no interference from
114 other activities on the system.
115
116
117 The cpustat utility must be run by the super-user, as there is an
118 intrinsic conflict between the use of the CPU performance counters sys‐
119 tem-wide by cpustat and the use of the CPU performance counters to mon‐
120 itor an individual process (for example, by cputrack.)
121
122
123 Once any instance of this utility has started, no further per-process
124 or per-LWP use of the counters is allowed until the last instance of
125 the utility terminates.
126
127
128 The times printed by the command correspond to the wallclock time when
129 the hardware counters were actually sampled, instead of when the pro‐
130 gram told the kernel to sample them. The time is derived from the same
131 timebase as gethrtime(3C).
132
133
134 The processor cycle counts enabled by the -t option always apply to
135 both user and system modes, regardless of the settings applied to the
136 performance counter registers.
137
138
139 On some hardware platforms running in system mode using the "sys"
140 token, the counters are implemented using 32-bit registers. While the
141 kernel attempts to catch all overflows to synthesize 64-bit counters,
142 because of hardware implementation restrictions, overflows can be lost
143 unless the sampling interval is kept short enough. The events most
144 prone to wrap are those that count processor clock cycles. If such an
145 event is of interest, sampling should occur frequently so that less
146 than 4 billion clock cycles can occur between samples.
147
148
149 The output of cpustat is designed to be readily parseable by nawk(1)
150 and perl(1), thereby allowing performance tools to be composed by
151 embedding cpustat in scripts. Alternatively, tools can be constructed
152 directly using the same APIs that cpustat is built upon using the
153 facilities of libcpc(3LIB). See cpc(3CPC).
154
155
156 The cpustat utility only monitors the CPUs that are accessible to it in
157 the current processor set. Thus, several instances of the utility can
158 be running on the CPUs in different processor sets. See psrset(1M) for
159 more information about processor sets.
160
161
162 Because cpustat uses LWPs bound to CPUs, the utility might have to be
163 terminated before the configuration of the relevant processor can be
164 changed.
165
167 SPARC
168 Example 1 Measuring External Cache References and Misses
169
170
171 The following example measures misses and references in the external
172 cache. These occur while the processor is operating in user mode on an
173 UltraSPARC machine.
174
175
176 example% cpustat -c EC_ref,EC_misses 1 3
177
178 time cpu event pic0 pic1
179 1.008 0 tick 69284 1647
180 1.008 1 tick 43284 1175
181 2.008 0 tick 179576 1834
182 2.008 1 tick 202022 12046
183 3.008 0 tick 93262 384
184 3.008 1 tick 63649 1118
185 3.008 2 total 651077 18204
186
187
188
189 x86
190 Example 2 Measuring Branch Prediction Success on Pentium 4
191
192
193 The following example measures branch mispredictions and total branch
194 instructions in user and system mode on a Pentium 4 machine.
195
196
197 example% cpustat -c \
198 pic12=branch_retired,emask12=0x4,pic14=branch_retired,\
199 emask14=0xf,sys 1 3
200
201 time cpu event pic12 pic14
202 1.010 1 tick 458 684
203 1.010 0 tick 305 511
204 2.010 0 tick 181 269
205 2.010 1 tick 469 684
206 3.010 0 tick 182 269
207 3.010 1 tick 468 684
208 3.010 2 total 2063 3101
209
210
211
212 Example 3 Counting Memory Accesses on Opteron
213
214
215 The following example determines the number of memory accesses made
216 through each memory controller on an Opteron, broken down by internal
217 memory latency:
218
219
220 cpustat -c \
221 pic0=NB_mem_ctrlr_page_access,umask0=0x01, \
222 pic1=NB_mem_ctrlr_page_access,umask1=0x02, \
223 pic2=NB_mem_ctrlr_page_access,umask2=0x04,sys \
224 1
225
226 time cpu event pic0 pic1 pic2
227 1.003 0 tick 41976 53519 7720
228 1.003 1 tick 5589 19402 731
229 2.003 1 tick 6011 17005 658
230 2.003 0 tick 43944 45473 7338
231 3.003 1 tick 7105 20177 762
232 3.003 0 tick 47045 48025 7119
233 4.003 0 tick 43224 46296 6694
234 4.003 1 tick 5366 19114 652
235
236
237
239 By running the cpustat command, the super-user forcibly invalidates all
240 existing performance counter context. This can in turn cause all invo‐
241 cations of the cputrack command, and other users of performance counter
242 context, to exit prematurely with unspecified errors.
243
244
245 If cpustat is invoked on a system that has CPU performance counters
246 which are not supported by Solaris, the following message appears:
247
248 cpustat: cannot access performance counters - Operation not applicable
249
250
251
252
253 This error message implies that cpc_open() has failed and is documented
254 in cpc_open(3CPC). Review this documentation for more information about
255 the problem and possible solutions.
256
257
258 If a short interval is requested, cpustat might not be able to keep up
259 with the desired sample rate. In this case, some samples might be
260 dropped.
261
263 See attributes(5) for descriptions of the following attributes:
264
265
266
267
268 ┌─────────────────────────────┬─────────────────────────────┐
269 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
270 ├─────────────────────────────┼─────────────────────────────┤
271 │Availability │SUNWcpcu │
272 ├─────────────────────────────┼─────────────────────────────┤
273 │Interface Stability │Evolving │
274 └─────────────────────────────┴─────────────────────────────┘
275
277 cputrack(1), nawk(1), perl(1), iostat(1M), prstat(1M), psrset(1M),
278 vmstat(1M), cpc(3CPC), cpc_open(3CPC), cpc_bind_cpu(3CPC), geth‐
279 rtime(3C), strtoll(3C), libcpc(3LIB), attributes(5)
280
282 When cpustat is run on a Pentium 4 with HyperThreading enabled, a CPC
283 set is bound to only one logical CPU of each physical CPU. See
284 cpc_bind_cpu(3CPC).
285
286
287
288SunOS 5.11 16 Jun 2009 cpustat(1M)