1cputrack(1)                      User Commands                     cputrack(1)
2
3
4

NAME

6       cputrack - monitor process and LWP behavior using CPU performance coun‐
7       ters
8

SYNOPSIS

10       cputrack -c eventspec [-c eventspec]... [-efntvD]
11            [-N count] [-o pathname] [-T interval] command [args]
12
13
14       cputrack -c eventspec [-c eventspec]... -p pid [-efntvD]
15            [-N count] [-o pathname] [-T interval]
16
17
18       cputrack -h
19
20

DESCRIPTION

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
33
34       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

OPTIONS

39       The following options are supported:
40
41       -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
45                         [picn=]eventn[,attr[n][=val]][,[picn=]eventn
46                              [,attr[n][=val]],...,]
47
48
49                       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
55                       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
63                       The  semantics  of  these  event  specifications can be
64                       determined by reading the CPU manufacturer's documenta‐
65                       tion for the events.
66
67                       Multiple  -c  options  can  be specified, in which case
68                       cputrack cycles between the different event settings on
69                       each sample.
70
71
72       -D              Enables debug mode.
73
74
75       -e              Follows all exec(2), or execve(2) system calls.
76
77
78       -f              Follows  all  children created by fork(2), fork1(2), or
79                       vfork(2) system calls.
80
81
82       -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
86
87       -n              Omits all header output  (useful  if  cputrack  is  the
88                       beginning of a pipeline).
89
90
91       -N count        Specifies the maximum number of CPU performance counter
92                       samples to take before exiting.
93
94
95       -o outfile      Specifies file to be used for the cputrack output.
96
97
98       -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
102
103       -t              Prints an additional column of processor cycle  counts,
104                       if available on the current architecture.
105
106
107       -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
111
112       -v              Enables more verbose output.
113
114

USAGE

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
124
125       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
129
130       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
134
135       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
141
142       Once an instance of the cpustat utility is running, further attempts to
143       run cputrack will fail until all instances of cpustat terminate.
144
145
146       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
154
155       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
159
160       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
166
167       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
174
175       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

EXAMPLES

181   SPARC
182       Example 1 Using Performance Counters to Count Clock Cycles
183
184
185       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
190
191         example% cputrack -c pic0=Cycle_cnt,pic1=Instr_cnt sleep 10
192
193
194           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
203
204
205
206       Example 2 Counting External Cache References and Misses
207
208
209       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
215
216         example% cputrack -fev -c EC_ref,EC_hit /bin/ulimit -c
217
218
219         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
240
241
242   x86
243       Example 3 Counting Instructions
244
245
246       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
249
250         example% cputrack -c inst_retired,inst_retired,nouser1,sys1 date
251
252
253            time lwp      event      pic0      pic1
254         Fri Aug 20 20:03:08 PDT 1999
255           0.072   1       exit    246725    339666
256
257
258
259       Example 4 Counting TLB Hits
260
261
262       This example shows how to use processor-specific  attributes  to  count
263       TLB hits on a Pentium 4 machine:
264
265
266         example% cputrack -c ITLB_reference,emask=1 date
267
268
269             time lwp      event      pic0
270               Fri Aug 20 20:03:08 PDT 1999
271            0.072   1       exit    246725
272
273
274

WARNINGS

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
281
282       If cpustat is invoked on a system that  has  CPU  performance  counters
283       which are not supported by Solaris, the following message appears:
284
285         cputrack: cannot access performance counters - Operation not applicable
286
287
288
289
290       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
294
295       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

ATTRIBUTES

300       See attributes(5) for descriptions of the following attributes:
301
302
303
304
305       ┌─────────────────────────────┬─────────────────────────────┐
306       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
307       ├─────────────────────────────┼─────────────────────────────┤
308       │Availability                 │SUNWcpcu                     │
309       │Interface Stability          │Evolving                     │
310       └─────────────────────────────┴─────────────────────────────┘
311

SEE ALSO

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)
317
318
319
320SunOS 5.11                        19 Apr 2004                      cputrack(1)
Impressum