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