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