1cputrack(1) User Commands cputrack(1)
2
6 cputrack - monitor process and LWP behavior using CPU performance coun‐
7 ters
8
10 cputrack -c eventspec [-c eventspec]... [-efntvD]
11 [-N count] [-o pathname] [-T interval] command [args]
12 cputrack -c eventspec [-c eventspec]... -p pid [-efntvD]
15 [-N count] [-o pathname] [-T interval]
16 cputrack -h
19
22 The cputrack utility allows CPU performance counters to be used to mon‐
23 itor the behavior of a process or family of processes running on the
24 system. If interval is specified with the -T option, cputrack samples
25 activity every interval seconds, repeating forever. If a count is spec‐
26 ified with the -N option, the statistics are repeated count times for
27 each process tracked. If neither are specified, an interval of one sec‐
28 ond is used. If command and optional args are specified, cputrack runs
29 the command with the arguments given while monitoring the specified CPU
30 performance events. Alternatively, the process ID of an existing
31 process can be specified using the -p option.
32 Because cputrack is an unprivileged program, it is subject to the same
35 restrictions that apply to truss(1). For example, setuid(2) executables
36 cannot be tracked.
37
39 The following options are supported:
40 -c eventspec Specifies a set of events for the CPU performance coun‐
42 ters to monitor. The syntax of these event specifica‐
43 tions is:
44 [picn=]eventn[,attr[n][=val]][,[picn=]eventn
46 [,attr[n][=val]],...,]
47 You can use the -h option to obtain a list of available
50 events and attributes. This causes generation of the
51 usage message. You can omit an explicit counter assign‐
52 ment, in which case cpustat attempts to choose a capa‐
53 ble counter automatically.
54 Attribute values can be expressed in hexadecimal,
56 octal, or decimal notation, in a format suitable for
57 strtoll(3C). An attribute present in the event specifi‐
58 cation without an explicit value receives a default
59 value of 1. An attribute without a corresponding
60 counter number is applied to all counters in the speci‐
61 fication.
62 The semantics of these event specifications can be
64 determined by reading the CPU manufacturer's documenta‐
65 tion for the events.
66 Multiple -c options can be specified, in which case
68 cputrack cycles between the different event settings on
69 each sample.
70 -D Enables debug mode.
73 -e Follows all exec(2), or execve(2) system calls.
76 -f Follows all children created by fork(2), fork1(2), or
79 vfork(2) system calls.
80 -h Prints an extended help message on how to use the util‐
83 ity, how to program the processor-dependent counters,
84 and where to look for more detailed information.
85 -n Omits all header output (useful if cputrack is the
88 beginning of a pipeline).
89 -N count Specifies the maximum number of CPU performance counter
92 samples to take before exiting.
93 -o outfile Specifies file to be used for the cputrack output.
96 -p pid Interprets the argument as the process ID of an exist‐
99 ing process to which process counter context should be
100 attached and monitored.
101 -t Prints an additional column of processor cycle counts,
104 if available on the current architecture.
105 -T interval Specifies the interval between CPU performance counter
108 samples in seconds. Very small intervals may cause some
109 samples to be skipped. See WARNINGS.
110 -v Enables more verbose output.
113
116 The operating system enforces certain restrictions on the tracing of
117 processes. In particular, a command whose object file cannot be read by
118 a user cannot be tracked by that user; set-uid and set-gid commands can
119 only be tracked by a privileged user. Unless it is run by a privileged
120 user, cputrack loses control of any process that performs an exec() of
121 a set-id or unreadable object file. Such processes continue normally,
122 though independently of cputrack, from the point of the exec().
123 The system may run out of per-user process slots when the -f option is
126 used, since cputrack runs one controlling process for each process
127 being tracked.
128 The times printed by cputrack correspond to the wallclock time when the
131 hardware counters were actually sample. The time is derived from the
132 same timebase as gethrtime(3C).
133 The cputrack utility attaches performance counter context to each
136 process that it examines. The presence of this context allows the per‐
137 formance counters to be multiplexed between different processes on the
138 system, but it cannot be used at the same time as the cpustat(1M) util‐
139 ity.
140 Once an instance of the cpustat utility is running, further attempts to
143 run cputrack will fail until all instances of cpustat terminate.
144 Sometimes cputrack provides sufficient flexibility and prints suffi‐
147 cient statistics to make adding the observation code to an application
148 unnecessary. However, more control is occasionally desired. Because the
149 same performance counter context is used by both the application itself
150 and by the agent LWP injected into the application by cputrack, it is
151 possible for an application to interact with the counter context to
152 achieve some interesting capabilities. See cpc_enable(3CPC).
153 The processor cycle counts enabled by the -t option always apply to
156 both user and system modes, regardless of the settings applied to the
157 performance counter registers.
158 The output of cputrack is designed to be readily parseable by nawk(1)
161 and perl(1), thereby allowing performance tools to be composed by
162 embedding cputrack in scripts. Alternatively, tools may be constructed
163 directly using the same APIs that cputrack is built upon, using the
164 facilities of libcpc(3LIB) and libpctx(3LIB). See cpc(3CPC).
165 Although cputrack uses performance counter context to maintain separate
168 performance counter values for each LWP, some of the events that can be
169 counted will inevitably be impacted by other activities occurring on
170 the system, particularly for limited resources that are shared between
171 processes (for example, cache miss rates). For such events, it may also
172 be interesting to observe overall system behavior with cpustat(1M).
173 For the -T interval option, if interval is specified as zero, no peri‐
176 odic sampling is performed. The performance counters are only sampled
177 when the process creates or destroys an LWP, or it invokes fork(2),
178 exec(2), or exit(2).
179
181 SPARC
182 Example 1 Using Performance Counters to Count Clock Cycles
183 In this example, the utility is being used on a machine containing an
186 UltraSPARC-III+ processor. The counters are set to count processor
187 clock cycles and instructions dispatched in user mode while running the
188 sleep(1) command.
189 example% cputrack -c pic0=Cycle_cnt,pic1=Instr_cnt sleep 10
192 time lwp event pic0 pic1
195 1.007 1 tick 765308 219233
196 2.007 1 tick 0 0
197 4.017 1 tick 0 0
198 6.007 1 tick 0 0
199 8.007 1 tick 0 0
200 10.007 1 tick 0 0
201 10.017 1 exit 844703 228058
202 Example 2 Counting External Cache References and Misses
207 This example shows more verbose output while following the fork() and
210 exec() of a simple shell script on an UltraSPARC machine. The counters
211 are measuring the number of external cache references and external
212 cache misses. Notice that the explicit pic0 and pic1 names can be omit‐
213 ted where there are no ambiguities.
214 example% cputrack -fev -c EC_ref,EC_hit /bin/ulimit -c
217 time pid lwp event pic0 pic1
220 0.007 101142 1 init_lwp 805286 20023
221 0.023 101142 1 fork # 101143
222 0.026 101143 1 init_lwp 1015382 24461
223 0.029 101143 1 fini_lwp 1025546 25074
224 0.029 101143 1 exec 1025546 25074
225 0.000 101143 1 exec \
226 # '/usr/bin/sh /usr/bin/basename\
227 /bin/ulimit'
228 0.039 101143 1 init_lwp 1025546 25074
229 0.050 101143 1 fini_lwp 1140482 27806
230 0.050 101143 1 exec 1140482 27806
231 0.000 101143 1 exec # '/usr/bin/expr \
232 //bin/ulimit : [^/]/*$ : .*/* : $ | //bin/ulimi'
233 0.059 101143 1 init_lwp 1140482 27806
234 0.075 101143 1 fini_lwp 1237647 30207
235 0.075 101143 1 exit 1237647 30207
236 unlimited
237 0.081 101142 1 fini_lwp 953383 23814
238 0.081 101142 1 exit 953383 23814
239 x86
243 Example 3 Counting Instructions
244 This example shows how many instructions were executed in the applica‐
247 tion and in the kernel to print the date on a Pentium III machine:
248 example% cputrack -c inst_retired,inst_retired,nouser1,sys1 date
251 time lwp event pic0 pic1
254 Fri Aug 20 20:03:08 PDT 1999
255 0.072 1 exit 246725 339666
256 Example 4 Counting TLB Hits
260 This example shows how to use processor-specific attributes to count
263 TLB hits on a Pentium 4 machine:
264 example% cputrack -c ITLB_reference,emask=1 date
267 time lwp event pic0
270 Fri Aug 20 20:03:08 PDT 1999
271 0.072 1 exit 246725
272
276 By running any instance of the cpustat(1M) utility, all existing per‐
277 formance counter context is forcibly invalidated across the machine.
278 This may in turn cause all invocations of the cputrack command to exit
279 prematurely with unspecified errors.
280 If cpustat is invoked on a system that has CPU performance counters
283 which are not supported by Solaris, the following message appears:
284 cputrack: cannot access performance counters - Operation not applicable
286 This error message implies that cpc_open() has failed and is documented
291 in cpc_open(3CPC). Review this documentation for more information about
292 the problem and possible solutions.
293 If a short interval is requested, cputrack may not be able to keep up
296 with the desired sample rate. In this case, some samples may be
297 dropped.
298
300 See attributes(5) for descriptions of the following attributes:
301 ┌─────────────────────────────┬─────────────────────────────┐
306 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
307 ├─────────────────────────────┼─────────────────────────────┤
308 │Availability │SUNWcpcu │
309 │Interface Stability │Evolving │
310 └─────────────────────────────┴─────────────────────────────┘
311
313 nawk(1), perl(1), proc(1), truss(1), prstat(1M), cpustat(1M), exec(2),
314 exit(2), fork(2), setuid(2), vfork(2), gethrtime(3C), strtoll(3C),
315 cpc(3CPC), cpc_bind_pctx(3CPC), cpc_enable(3CPC), cpc_open(3CPC),
316 libcpc(3LIB), libpctx(3LIB), proc(4), attributes(5)
317SunOS 5.11 19 Apr 2004 cputrack(1)