usr/src/man/man1m/cpustat.1m

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.
   3 .TH CPUSTAT 1M "April 9, 2016"
   4 .SH NAME
   5 cpustat \- monitor system behavior using CPU performance counters
   6 .SH SYNOPSIS
   7 .LP
   8 .nf
   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]]
  11 .fi
  12
  13 .LP
  14 .nf
  15 \fBcpustat\fR \fB-h\fR
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBcpustat\fR utility allows \fBCPU\fR performance counters to be used to
  21 monitor the overall behavior of the \fBCPU\fRs in the system.
  22 .sp
  23 .LP
  24 If \fIinterval\fR is specified, \fBcpustat\fR samples activity every
  25 \fIinterval\fR seconds, repeating forever. If a \fIcount\fR is specified, the
  26 statistics are repeated \fIcount\fR times. If neither are specified, an
  27 interval of five seconds is used, and there is no limit to the number of
  28 samples that are taken.
  29 .SH OPTIONS
  30 .LP
  31 The following options are supported:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fB-c\fR \fIeventspec\fR\fR
  36 .ad
  37 .sp .6
  38 .RS 4n
  39 Specifies a set of events for the \fBCPU\fR performance counters to monitor.
  40 The syntax of these event specifications is:
  41 .sp
  42 .in +2
  43 .nf
  44 [picn=]\fIeventn\fR[,attr[\fIn\fR][=\fIval\fR]][,[picn=]\fIeventn\fR
  45      [,attr[n][=\fIval\fR]],...,]
  46 .fi
  47 .in -2
  48 .sp
  49
  50 You can use the \fB-h\fR option to obtain a list of available events and
  51 attributes. This causes generation of the usage message. You can omit an
  52 explicit counter assignment, in which case \fBcpustat\fR attempts to choose a
  53 capable counter automatically.
  54 .sp
  55 Attribute values can be expressed in hexadecimal, octal, or decimal notation,
  56 in a format suitable for \fBstrtoll\fR(3C). An attribute present in the event
  57 specification without an explicit value receives a default value of \fB1\fR. An
  58 attribute without a corresponding counter number is applied to all counters in
  59 the specification.
  60 .sp
  61 The semantics of these event specifications can be determined by reading the
  62 \fBCPU\fR manufacturer's documentation for the events.
  63 .sp
  64 Multiple \fB-c\fR options can be specified, in which case the command cycles
  65 between the different event settings on each sample.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fB-D\fR\fR
  72 .ad
  73 .sp .6
  74 .RS 4n
  75 Enables debug mode.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fB-h\fR\fR
  82 .ad
  83 .sp .6
  84 .RS 4n
  85 Prints an extensive help message on how to use the utility and how to program
  86 the processor-dependent counters.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB-n\fR\fR
  93 .ad
  94 .sp .6
  95 .RS 4n
  96 Omits all header output (useful if \fBcpustat\fR is the beginning of a
  97 pipeline).
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fB-p\fR \fIperiod\fR\fR
 104 .ad
 105 .sp .6
 106 .RS 4n
 107 Causes \fBcpustat\fR to cycle through the list of \fIeventspec\fRs every
 108 \fIperiod\fR seconds. The tool sleeps after each cycle until \fIperiod\fR
 109 seconds have elapsed since the first \fIeventspec\fR was measured.
 110 .sp
 111 When this option is present, the optional \fIcount\fR parameter specifies the
 112 number of total cycles to make (instead of the number of total samples to
 113 take). If \fIperiod\fR is less than the number of \fIeventspec\fRs times
 114 \fIinterval\fR, the tool acts as it period is \fB0\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-s\fR\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Creates an idle soaker thread to spin while system-only \fIeventspec\fRs are
 125 bound. One idle soaker thread is bound to each CPU in the current processor
 126 set. System-only \fIeventspec\fRs contain both the \fBnouser\fR and the
 127 \fBsys\fR tokens and measure events that occur while the CPU is operating in
 128 privileged mode. This option prevents the kernel's idle loop from running and
 129 triggering system-mode events.
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB-T\fR \fBu\fR | \fBd\fR\fR
 136 .ad
 137 .sp .6
 138 .RS 4n
 139 Display a time stamp.
 140 .sp
 141 Specify \fBu\fR for a printed representation of the internal representation of
 142 time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
 143 \fBdate\fR(1).
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fB-t\fR\fR
 150 .ad
 151 .sp .6
 152 .RS 4n
 153 Prints an additional column of processor cycle counts, if available on the
 154 current architecture.
 155 .RE
 156
 157 .SH USAGE
 158 .LP
 159 A closely related utility, \fBcputrack\fR(1), can be used to monitor the
 160 behavior of individual applications with little or no interference from other
 161 activities on the system.
 162 .sp
 163 .LP
 164 The \fBcpustat\fR utility must be run by the super-user, as there is an
 165 intrinsic conflict between the use of the \fBCPU\fR performance counters
 166 system-wide by \fBcpustat\fR and the use of the \fBCPU\fR performance counters
 167 to monitor an individual process (for example, by \fBcputrack\fR.)
 168 .sp
 169 .LP
 170 Once any instance of this utility has started, no further per-process or
 171 per-\fBLWP\fR use of the counters is allowed until the last instance of the
 172 utility terminates.
 173 .sp
 174 .LP
 175 The times printed by the command correspond to the wallclock time when the
 176 hardware counters were actually sampled, instead of when the program told the
 177 kernel to sample them. The time is derived from the same timebase as
 178 \fBgethrtime\fR(3C).
 179 .sp
 180 .LP
 181 The processor cycle counts enabled by the \fB-t\fR option always apply to both
 182 user and system modes, regardless of the settings applied to the performance
 183 counter registers.
 184 .sp
 185 .LP
 186 On some hardware platforms running in system mode using the "sys" token, the
 187 counters are implemented using 32-bit registers. While the kernel attempts to
 188 catch all overflows to synthesize 64-bit counters, because of hardware
 189 implementation restrictions, overflows can be lost unless the sampling interval
 190 is kept short enough. The events most prone to wrap are those that count
 191 processor clock cycles. If such an event is of interest, sampling should occur
 192 frequently so that less than 4 billion clock cycles can occur between samples.
 193 .sp
 194 .LP
 195 The output of cpustat is designed to be readily parsable by \fBnawk\fR(1) and
 196 \fBperl\fR(1), thereby allowing performance tools to be composed by embedding
 197 \fBcpustat\fR in scripts. Alternatively, tools can be constructed directly
 198 using the same \fBAPI\fRs that \fBcpustat\fR is built upon using the facilities
 199 of \fBlibcpc\fR(3LIB). See \fBcpc\fR(3CPC).
 200 .sp
 201 .LP
 202 The \fBcpustat\fR utility only monitors the \fBCPU\fRs that are accessible to
 203 it in the current processor set. Thus, several instances of the utility can be
 204 running on the \fBCPU\fRs in different processor sets. See \fBpsrset\fR(1M) for
 205 more information about processor sets.
 206 .sp
 207 .LP
 208 Because \fBcpustat\fR uses \fBLWP\fRs bound to \fBCPU\fRs, the utility might
 209 have to be terminated before the configuration of the relevant processor can be
 210 changed.
 211 .SH EXAMPLES
 212 .SS "SPARC"
 213 .LP
 214 \fBExample 1 \fRMeasuring External Cache References and Misses
 215 .sp
 216 .LP
 217 The following example measures misses and references in the external cache.
 218 These occur while the processor is operating in user mode on an UltraSPARC
 219 machine.
 220
 221 .sp
 222 .in +2
 223 .nf
 224 example% cpustat -c EC_ref,EC_misses 1 3
 225
 226     time cpu event      pic0      pic1
 227    1.008   0  tick     69284      1647
 228    1.008   1  tick     43284      1175
 229    2.008   0  tick    179576      1834
 230    2.008   1  tick    202022     12046
 231    3.008   0  tick     93262       384
 232    3.008   1  tick     63649      1118
 233    3.008   2 total    651077     18204
 234 .fi
 235 .in -2
 236 .sp
 237
 238 .SS "x86"
 239 .LP
 240 \fBExample 2 \fRMeasuring Branch Prediction Success on Pentium 4
 241 .sp
 242 .LP
 243 The following example measures branch mispredictions and total branch
 244 instructions in user and system mode on a Pentium 4 machine.
 245
 246 .sp
 247 .in +2
 248 .nf
 249  example% cpustat -c \e
 250     pic12=branch_retired,emask12=0x4,pic14=branch_retired,\e
 251     emask14=0xf,sys 1 3
 252
 253     time cpu event      pic12     pic14
 254    1.010   1  tick       458       684
 255    1.010   0  tick       305       511
 256    2.010   0  tick       181       269
 257    2.010   1  tick       469       684
 258    3.010   0  tick       182       269
 259    3.010   1  tick       468       684
 260    3.010   2 total      2063      3101
 261 .fi
 262 .in -2
 263 .sp
 264
 265 .LP
 266 \fBExample 3 \fRCounting Memory Accesses on Opteron
 267 .sp
 268 .LP
 269 The following example determines the number of memory accesses made through
 270 each memory controller on an Opteron, broken down by internal memory latency:
 271
 272 .sp
 273 .in +2
 274 .nf
 275 cpustat -c \e
 276    pic0=NB_mem_ctrlr_page_access,umask0=0x01, \e
 277    pic1=NB_mem_ctrlr_page_access,umask1=0x02, \e
 278    pic2=NB_mem_ctrlr_page_access,umask2=0x04,sys \e
 279    1
 280
 281     time cpu event      pic0      pic1      pic2
 282    1.003   0  tick     41976     53519      7720
 283    1.003   1  tick      5589     19402       731
 284    2.003   1  tick      6011     17005       658
 285    2.003   0  tick     43944     45473      7338
 286    3.003   1  tick      7105     20177       762
 287    3.003   0  tick     47045     48025      7119
 288    4.003   0  tick     43224     46296      6694
 289    4.003   1  tick      5366     19114       652
 290 .fi
 291 .in -2
 292 .sp
 293
 294 .SH WARNINGS
 295 .LP
 296 By running the \fBcpustat\fR command, the super-user forcibly invalidates all
 297 existing performance counter context. This can in turn cause all invocations of
 298 the \fBcputrack\fR command, and other users of performance counter context, to
 299 exit prematurely with unspecified errors.
 300 .sp
 301 .LP
 302 If \fBcpustat\fR is invoked on a system that has \fBCPU\fR performance counters
 303 which are not supported by Solaris, the following message appears:
 304 .sp
 305 .in +2
 306 .nf
 307 cpustat: cannot access performance counters - Operation not applicable
 308 .fi
 309 .in -2
 310 .sp
 311
 312 .sp
 313 .LP
 314 This error message implies that \fBcpc_open()\fR has failed and is documented
 315 in \fBcpc_open\fR(3CPC). Review this documentation for more information about
 316 the problem and possible solutions.
 317 .sp
 318 .LP
 319 If a short interval is requested, \fBcpustat\fR might not be able to keep up
 320 with the desired sample rate. In this case, some samples might be dropped.
 321 .SH ATTRIBUTES
 322 .LP
 323 See \fBattributes\fR(5) for descriptions of the following attributes:
 324 .sp
 325
 326 .sp
 327 .TS
 328 box;
 329 c | c
 330 l | l .
 331 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 332 _
 333 Interface Stability     Evolving
 334 .TE
 335
 336 .SH SEE ALSO
 337 .LP
 338 \fBcputrack\fR(1), \fBnawk\fR(1), \fBperl\fR(1), \fBiostat\fR(1M),
 339 \fBprstat\fR(1M), \fBpsrset\fR(1M), \fBvmstat\fR(1M), \fBcpc\fR(3CPC),
 340 \fBcpc_open\fR(3CPC), \fBcpc_bind_cpu\fR(3CPC), \fBgethrtime\fR(3C),
 341 \fBstrtoll\fR(3C), \fBlibcpc\fR(3LIB), \fBattributes\fR(5)
 342 .SH NOTES
 343 .LP
 344 When \fBcpustat\fR is run on a Pentium 4 with HyperThreading enabled, a CPC set
 345 is bound to only one logical CPU of each physical CPU. See
 346 \fBcpc_bind_cpu\fR(3CPC).