1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CPUTRACK 1 "Apr 19, 2004"
   7 .SH NAME
   8 cputrack \- monitor process and LWP behavior using CPU performance counters
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcputrack\fR \fB-c\fR \fIeventspec\fR [\fB-c\fR \fIeventspec\fR]... [\fB-efntvD\fR]
  13      [\fB-N\fR \fIcount\fR] [\fB-o\fR \fIpathname\fR] [\fB-T\fR \fIinterval\fR] \fIcommand\fR [\fIargs\fR]
  14 .fi
  15 
  16 .LP
  17 .nf
  18 \fBcputrack\fR \fB-c\fR \fIeventspec\fR [\fB-c\fR \fIeventspec\fR]... \fB-p\fR \fIpid\fR [\fB-efntvD\fR]
  19      [\fB-N\fR \fIcount\fR] [\fB-o\fR \fIpathname\fR] [\fB-T\fR \fIinterval\fR]
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBcputrack\fR \fB-h\fR
  25 .fi
  26 
  27 .SH DESCRIPTION
  28 .sp
  29 .LP
  30 The \fBcputrack\fR utility allows \fBCPU\fR performance counters to be used to
  31 monitor the behavior of a process or family of processes running on the system.
  32 If \fIinterval\fR is specified with the \fB-T\fR option, \fBcputrack\fR samples
  33 activity every \fIinterval\fR seconds, repeating forever. If a \fIcount\fR is
  34 specified with the \fB-N\fR option, the statistics are repeated \fIcount\fR
  35 times for each process tracked. If neither are specified, an interval of one
  36 second is used. If \fIcommand\fR and optional \fIargs\fR are specified,
  37 \fBcputrack\fR runs the command with the arguments given while monitoring the
  38 specified \fBCPU\fR performance events. Alternatively, the process \fBID\fR of
  39 an existing process can be specified using the \fB-p\fR option.
  40 .sp
  41 .LP
  42 Because \fBcputrack\fR is an unprivileged program, it is subject to the same
  43 restrictions that apply to \fBtruss\fR(1). For example, \fBsetuid\fR(2)
  44 executables cannot be tracked.
  45 .SH OPTIONS
  46 .sp
  47 .LP
  48 The following options are supported:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fB-c\fR \fIeventspec\fR\fR
  53 .ad
  54 .RS 16n
  55 Specifies a set of events for the \fBCPU\fR performance counters to monitor.
  56 The syntax of these event specifications is:
  57 .sp
  58 .in +2
  59 .nf
  60 [picn=]\fIeventn\fR[,attr[\fIn\fR][=\fIval\fR]][,[picn=]\fIeventn\fR
  61      [,attr[n][=\fIval\fR]],...,]
  62 .fi
  63 .in -2
  64 .sp
  65 
  66 You can use the \fB-h\fR option to obtain a list of available events and
  67 attributes. This causes generation of the usage message. You can omit an
  68 explicit counter assignment, in which case \fBcpustat\fR attempts to choose a
  69 capable counter automatically.
  70 .sp
  71 Attribute values can be expressed in hexadecimal, octal, or decimal notation,
  72 in a format suitable for \fBstrtoll\fR(3C). An attribute present in the event
  73 specification without an explicit value receives a default value of \fB1\fR. An
  74 attribute without a corresponding counter number is applied to all counters in
  75 the specification.
  76 .sp
  77 The semantics of these event specifications can be determined by reading the
  78 \fBCPU\fR manufacturer's documentation for the events.
  79 .sp
  80 Multiple \fB-c\fR options can be specified, in which case \fBcputrack\fR cycles
  81 between the different event settings on each sample.
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fB-D\fR\fR
  88 .ad
  89 .RS 16n
  90 Enables debug mode.
  91 .RE
  92 
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fB-e\fR\fR
  97 .ad
  98 .RS 16n
  99 Follows all \fBexec\fR(2), or \fBexecve\fR(2) system calls.
 100 .RE
 101 
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fB-f\fR\fR
 106 .ad
 107 .RS 16n
 108 Follows all children created by \fBfork\fR(2), \fBfork1\fR(2), or
 109 \fBvfork\fR(2) system calls.
 110 .RE
 111 
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fB-h\fR\fR
 116 .ad
 117 .RS 16n
 118 Prints an extended help message on how to use the utility, how to program the
 119 processor-dependent counters, and where to look for more detailed information.
 120 .RE
 121 
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fB-n\fR\fR
 126 .ad
 127 .RS 16n
 128 Omits all header output (useful if \fBcputrack\fR is the beginning of a
 129 pipeline).
 130 .RE
 131 
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB-N\fR \fIcount\fR\fR
 136 .ad
 137 .RS 16n
 138 Specifies the maximum number of \fBCPU\fR performance counter samples to take
 139 before exiting.
 140 .RE
 141 
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fB-o\fR \fIoutfile\fR\fR
 146 .ad
 147 .RS 16n
 148 Specifies file to be used for the \fBcputrack\fR output.
 149 .RE
 150 
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fB-p\fR \fIpid\fR\fR
 155 .ad
 156 .RS 16n
 157 Interprets the argument as the process \fBID\fR of an existing process to which
 158 process counter context should be attached and monitored.
 159 .RE
 160 
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fB-t\fR\fR
 165 .ad
 166 .RS 16n
 167 Prints an additional column of processor cycle counts, if available on the
 168 current architecture.
 169 .RE
 170 
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fB-T\fR \fIinterval\fR\fR
 175 .ad
 176 .RS 16n
 177 Specifies the interval between \fBCPU\fR performance counter samples in
 178 seconds. Very small intervals may cause some samples to be skipped. See
 179 WARNINGS.
 180 .RE
 181 
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fB-v\fR\fR
 186 .ad
 187 .RS 16n
 188 Enables more verbose output.
 189 .RE
 190 
 191 .SH USAGE
 192 .sp
 193 .LP
 194 The operating system enforces certain restrictions on the tracing of processes.
 195 In particular, a command whose object file cannot be read by a user cannot be
 196 tracked by that user; set-uid and set-gid commands can only be tracked by a
 197 privileged user. Unless it is run by a privileged user, \fBcputrack\fR loses
 198 control of any process that performs an \fBexec()\fR of a set-id or unreadable
 199 object file. Such processes continue normally, though independently of
 200 \fBcputrack\fR, from the point of the \fBexec()\fR.
 201 .sp
 202 .LP
 203 The system may run out of per-user process slots when the \fB-f\fR option is
 204 used, since \fBcputrack\fR runs one controlling process for each process being
 205 tracked.
 206 .sp
 207 .LP
 208 The times printed by \fBcputrack\fR correspond to the wallclock time when the
 209 hardware counters were actually sample. The time is derived from the same
 210 timebase as \fBgethrtime\fR(3C).
 211 .sp
 212 .LP
 213 The \fBcputrack\fR utility attaches performance counter context to each process
 214 that it examines. The presence of this context allows the performance counters
 215 to be multiplexed between different processes on the system, but it cannot be
 216 used at the same time as the \fBcpustat\fR(1M) utility.
 217 .sp
 218 .LP
 219 Once an instance of the \fBcpustat\fR utility is running, further attempts to
 220 run \fBcputrack\fR will fail until all instances of \fBcpustat\fR terminate.
 221 .sp
 222 .LP
 223 Sometimes \fBcputrack\fR provides sufficient flexibility and prints sufficient
 224 statistics to make adding the observation code to an application unnecessary.
 225 However, more control is occasionally desired. Because the same performance
 226 counter context is used by both the application itself and by the agent LWP
 227 injected into the application by \fBcputrack\fR, it is possible for an
 228 application to interact with the counter context to achieve some interesting
 229 capabilities. See \fBcpc_enable\fR(3CPC).
 230 .sp
 231 .LP
 232 The processor cycle counts enabled by the \fB-t\fR option always apply to both
 233 user and system modes, regardless of the settings applied to the performance
 234 counter registers.
 235 .sp
 236 .LP
 237 The output of \fBcputrack\fR is designed to be readily parseable by
 238 \fBnawk\fR(1) and \fBperl\fR(1), thereby allowing performance tools to be
 239 composed by embedding \fBcputrack\fR in scripts. Alternatively, tools may be
 240 constructed directly using the same \fBAPI\fRs that \fBcputrack\fR is built
 241 upon, using the facilities of \fBlibcpc\fR(3LIB) and \fBlibpctx\fR(3LIB). See
 242 \fBcpc\fR(3CPC).
 243 .sp
 244 .LP
 245 Although \fBcputrack\fR uses performance counter context to maintain separate
 246 performance counter values for each LWP, some of the events that can be counted
 247 will inevitably be impacted by other activities occurring on the system,
 248 particularly for limited resources that are shared between processes (for
 249 example, cache miss rates). For such events, it may also be interesting to
 250 observe overall system behavior with \fBcpustat\fR(1M).
 251 .sp
 252 .LP
 253 For the \fB-T\fR \fIinterval\fR option, if \fIinterval\fR is specified as zero,
 254 no periodic sampling is performed. The performance counters are only sampled
 255 when the process creates or destroys an \fBLWP\fR, or it invokes \fBfork\fR(2),
 256 \fBexec\fR(2), or \fBexit\fR(2).
 257 .SH EXAMPLES
 258 .SS "SPARC"
 259 .LP
 260 \fBExample 1 \fRUsing Performance Counters to Count Clock Cycles
 261 .sp
 262 .LP
 263 In this example, the utility is being used on a machine containing an
 264 UltraSPARC-III+ processor. The counters are set to count processor clock cycles
 265 and instructions dispatched in user mode while running the \fBsleep\fR(1)
 266 command.
 267 
 268 .sp
 269 .in +2
 270 .nf
 271 example% \fBcputrack -c pic0=Cycle_cnt,pic1=Instr_cnt sleep 10\fR
 272 
 273 
 274   time lwp      event      pic0      pic1
 275  1.007   1       tick    765308    219233
 276  2.007   1       tick         0         0
 277  4.017   1       tick         0         0
 278  6.007   1       tick         0         0
 279  8.007   1       tick         0         0
 280 10.007   1       tick         0         0
 281 10.017   1       exit    844703    228058
 282 
 283 .fi
 284 .in -2
 285 .sp
 286 
 287 .LP
 288 \fBExample 2 \fRCounting External Cache References and Misses
 289 .sp
 290 .LP
 291 This example shows more verbose output while following the \fBfork()\fR and
 292 \fBexec()\fR of a simple shell script on an UltraSPARC machine. The counters
 293 are measuring the number of external cache references and external cache
 294 misses. Notice that the explicit \fBpic0\fR and \fBpic1\fR names can be omitted
 295 where there are no ambiguities.
 296 
 297 .sp
 298 .in +2
 299 .nf
 300 example% \fBcputrack -fev -c EC_ref,EC_hit /bin/ulimit -c\fR
 301 
 302 
 303 time    pid lwp      event      pic0      pic1
 304 0.007 101142   1   init_lwp    805286     20023
 305 0.023 101142   1       fork                     # 101143
 306 0.026 101143   1   init_lwp   1015382     24461
 307 0.029 101143   1   fini_lwp   1025546     25074
 308 0.029 101143   1       exec   1025546     25074
 309 0.000 101143   1       exec                     \e
 310                                       # '/usr/bin/sh /usr/bin/basename\e
 311                                          /bin/ulimit'
 312 0.039 101143   1   init_lwp   1025546     25074
 313 0.050 101143   1   fini_lwp   1140482     27806
 314 0.050 101143   1       exec   1140482     27806
 315 0.000 101143   1       exec                     # '/usr/bin/expr \e
 316    //bin/ulimit : \(.*[^/]\)/*$ : .*/\(..*\) : \(.*\)$ | //bin/ulimi'
 317 0.059 101143   1   init_lwp   1140482     27806
 318 0.075 101143   1   fini_lwp   1237647     30207
 319 0.075 101143   1       exit   1237647     30207
 320 unlimited
 321 0.081 101142   1   fini_lwp    953383     23814
 322 0.081 101142   1       exit    953383     23814
 323 .fi
 324 .in -2
 325 .sp
 326 
 327 .SS "x86"
 328 .LP
 329 \fBExample 3 \fRCounting Instructions
 330 .sp
 331 .LP
 332 This example shows how many instructions were executed in the application and
 333 in the kernel to print the date on a Pentium III machine:
 334 
 335 .sp
 336 .in +2
 337 .nf
 338 example% \fBcputrack -c inst_retired,inst_retired,nouser1,sys1 date\fR
 339 
 340 
 341    time lwp      event      pic0      pic1
 342 Fri Aug 20 20:03:08 PDT 1999
 343   0.072   1       exit    246725    339666
 344 .fi
 345 .in -2
 346 .sp
 347 
 348 .LP
 349 \fBExample 4 \fRCounting TLB Hits
 350 .sp
 351 .LP
 352 This example shows how to use processor-specific attributes to count TLB hits
 353 on a Pentium 4 machine:
 354 
 355 .sp
 356 .in +2
 357 .nf
 358 example% \fBcputrack -c ITLB_reference,emask=1 date\fR
 359 
 360 
 361     time lwp      event      pic0
 362       Fri Aug 20 20:03:08 PDT 1999
 363    0.072   1       exit    246725
 364 .fi
 365 .in -2
 366 .sp
 367 
 368 .SH WARNINGS
 369 .sp
 370 .LP
 371 By running any instance of the \fBcpustat\fR(1M) utility, all existing
 372 performance counter context is forcibly invalidated across the machine. This
 373 may in turn cause all invocations of the \fBcputrack\fR command to exit
 374 prematurely with unspecified errors.
 375 .sp
 376 .LP
 377 If \fBcpustat\fR is invoked on a system that has \fBCPU\fR performance counters
 378 which are not supported by Solaris, the following message appears:
 379 .sp
 380 .in +2
 381 .nf
 382 cputrack: cannot access performance counters - Operation not applicable
 383 .fi
 384 .in -2
 385 .sp
 386 
 387 .sp
 388 .LP
 389 This error message implies that \fBcpc_open()\fR has failed and is documented
 390 in \fBcpc_open\fR(3CPC). Review this documentation for more information about
 391 the problem and possible solutions.
 392 .sp
 393 .LP
 394 If a short interval is requested, \fBcputrack\fR may not be able to keep up
 395 with the desired sample rate. In this case, some samples may be dropped.
 396 .SH ATTRIBUTES
 397 .sp
 398 .LP
 399 See \fBattributes\fR(5) for descriptions of the following attributes:
 400 .sp
 401 
 402 .sp
 403 .TS
 404 box;
 405 c | c
 406 l | l .
 407 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 408 Interface Stability     Evolving
 409 .TE
 410 
 411 .SH SEE ALSO
 412 .sp
 413 .LP
 414 \fBnawk\fR(1), \fBperl\fR(1), \fBproc\fR(1), \fBtruss\fR(1), \fBprstat\fR(1M),
 415 \fBcpustat\fR(1M), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2),
 416 \fBsetuid\fR(2), \fBvfork\fR(2), \fBgethrtime\fR(3C), \fBstrtoll\fR(3C),
 417 \fBcpc\fR(3CPC), \fBcpc_bind_pctx\fR(3CPC), \fBcpc_enable\fR(3CPC),
 418 \fBcpc_open\fR(3CPC), \fBlibcpc\fR(3LIB), \fBlibpctx\fR(3LIB), \fBproc\fR(4),
 419 \fBattributes\fR(5)