1cpustat(1M)             System Administration Commands             cpustat(1M)
2
3
4

NAME

6       cpustat - monitor system behavior using CPU performance counters
7

SYNOPSIS

9       cpustat -c eventspec [-c eventspec]... [-p period] [-T u | d ]
10            [-sntD] [interval [count]]
11
12
13       cpustat -h
14
15

DESCRIPTION

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

OPTIONS

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

USAGE

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

EXAMPLES

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

WARNINGS

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

ATTRIBUTES

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

SEE ALSO

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

NOTES

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)
Impressum