summaryrefslogtreecommitdiffstats
path: root/usr.sbin/pmcstat/pmcstat.8
blob: a4e6f1f87a42eecbf0da1c7a2f196dff06cc155c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
.\" Copyright (c) 2003-2008 Joseph Koshy
.\" Copyright (c) 2007 The FreeBSD Foundation
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" This software is provided by Joseph Koshy ``as is'' and
.\" any express or implied warranties, including, but not limited to, the
.\" implied warranties of merchantability and fitness for a particular purpose
.\" are disclaimed.  in no event shall Joseph Koshy be liable
.\" for any direct, indirect, incidental, special, exemplary, or consequential
.\" damages (including, but not limited to, procurement of substitute goods
.\" or services; loss of use, data, or profits; or business interruption)
.\" however caused and on any theory of liability, whether in contract, strict
.\" liability, or tort (including negligence or otherwise) arising in any way
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
.\" $FreeBSD$
.\"
.Dd September 19, 2008
.Os
.Dt PMCSTAT 8
.Sh NAME
.Nm pmcstat
.Nd "performance measurement with performance monitoring hardware"
.Sh SYNOPSIS
.Nm
.Op Fl C
.Op Fl D Ar pathname
.Op Fl E
.Op Fl G Ar pathname
.Op Fl M Ar mapfilename
.Op Fl N
.Op Fl O Ar logfilename
.Op Fl P Ar event-spec
.Op Fl R Ar logfilename
.Op Fl S Ar event-spec
.Op Fl W
.Op Fl c Ar cpu-spec
.Op Fl d
.Op Fl g
.Op Fl k Ar kerneldir
.Op Fl m Ar pathname
.Op Fl n Ar rate
.Op Fl o Ar outputfile
.Op Fl p Ar event-spec
.Op Fl q
.Op Fl r Ar fsroot
.Op Fl s Ar event-spec
.Op Fl t Ar process-spec
.Op Fl v
.Op Fl w Ar secs
.Op Fl z Ar graphdepth
.Op Ar command Op Ar args
.Sh DESCRIPTION
The
.Nm
utility measures system performance using the facilities provided by
.Xr hwpmc 4 .
.Pp
The
.Nm
utility can measure both hardware events seen by the system as a
whole, and those seen when a specified set of processes are executing
on the system's CPUs.
If a specific set of processes is being targeted (for example,
if the
.Fl t Ar process-spec
option is specified, or if a command line is specified using
.Ar command ) ,
then measurement occurs till
.Ar command
exits, or till all target processes specified by the
.Fl t Ar process-spec
options exit, or till the
.Nm
utility is interrupted by the user.
If a specific set of processes is not targeted for measurement, then
.Nm
will perform system-wide measurements till interrupted by the
user.
.Pp
A given invocation of
.Nm
can mix allocations of system-mode and process-mode PMCs, of both
counting and sampling flavors.
The values of all counting PMCs are printed in human readable form
at regular intervals by
.Nm .
The output of sampling PMCs may be configured to go to a log file for
subsequent offline analysis, or, at the expense of greater
overhead, may be configured to be printed in text form on the fly.
.Pp
Hardware events to measure are specified to
.Nm
using event specifier strings
.Ar event-spec .
The syntax of these event specifiers is machine dependent and is
documented in
.Xr pmc 3 .
.Pp
A process-mode PMC may be configured to be inheritable by the target
process' current and future children.
.Sh OPTIONS
The following options are available:
.Bl -tag -width indent
.It Fl C
Toggle between showing cumulative or incremental counts for
subsequent counting mode PMCs specified on the command line.
The default is to show incremental counts.
.It Fl D Ar pathname
Create files with per-program samples in the directory named
by
.Ar pathname .
The default is to create these files in the current directory.
.It Fl E
Toggle showing per-process counts at the time a tracked process
exits for subsequent process-mode PMCs specified on the command line.
This option is useful for mapping the performance characteristics of a
complex pipeline of processes when used in conjunction with the
.Fl d
option.
The default is to not to enable per-process tracking.
.It Fl G Ar pathname
Print callchain information to file
.Ar pathname .
If argument
.Ar pathname
is a
.Dq Li -
this information is sent to the output file specified by the
.Fl o
option.
.It Fl M Ar mapfilename
Write the mapping between executable objects encountered in the event
log and the abbreviated pathnames used for
.Xr gprof 1
profiles to file
.Ar mapfilename .
If this option is not specified, mapping information is not written.
Argument
.Ar mapfilename
may be a
.Dq Li -
in which case this mapping information is sent to the output
file configured by the
.Fl o
option.
.It Fl N
Toggle capturing callchain information for subsequent sampling PMCs.
The default is for sampling PMCs to capture callchain information.
.It Fl O Ar logfilename
Send logging output to file
.Ar logfilename .
If
.Ar logfilename
is of the form
.Ar hostname Ns : Ns Ar port ,
where
.Ar hostname
does not start with a
.Ql \&.
or a
.Ql / ,
then
.Nm
will open a network socket to host
.Ar hostname
on port
.Ar port .
.Pp
If the
.Fl O
option is not specified and one of the logging options is requested,
then
.Nm
will print a textual form of the logged events to the configured
output file.
.It Fl P Ar event-spec
Allocate a process mode sampling PMC measuring hardware events
specified in
.Ar event-spec .
.It Fl R Ar logfilename
Perform offline analysis using sampling data in file
.Ar logfilename .
.It Fl S Ar event-spec
Allocate a system mode sampling PMC measuring hardware events
specified in
.Ar event-spec .
.It Fl W
Toggle logging the incremental counts seen by the threads of a
tracked process each time they are scheduled on a CPU.
This is an experimental feature intended to help analyse the
dynamic behaviour of processes in the system.
It may incur substantial overhead if enabled.
The default is for this feature to be disabled.
.It Fl c Ar cpu-spec
Set the cpus for subsequent system mode PMCs specified on the
command line to
.Ar cpu-spec .
Argument
.Ar cpu-spec
is a comma separated list of CPU numbers, or the literal
.Sq *
denoting all unhalted CPUs.
The default is to allocate system mode PMCs on all unhalted
CPUs.
.It Fl d
Toggle between process mode PMCs measuring events for the target
process' current and future children or only measuring events for
the target process.
The default is to measure events for the target process alone.
.It Fl g
Produce profiles in a format compatible with
.Xr gprof 1 .
A separate profile file is generated for each executable object
encountered.
Profile files are placed in sub-directories named by their PMC
event name.
.It Fl k Ar kerneldir
Set the pathname of the kernel directory to argument
.Ar kerneldir .
This directory specifies where
.Nm
should look for the kernel and its modules.
The default is
.Pa /boot/kernel .
.It Fl m Ar pathname
Print the sampled PCs with the name, the start and ending addresses
of the function within they live.
The
.Ar pathname
argument is mandatory and indicates where informations will be stored.
If argument
.Ar pathname
is a
.Dq Li -
this information is sent to the output file specified by the
.Fl o
option.
.It Fl n Ar rate
Set the default sampling rate for subsequent sampling mode
PMCs specified on the command line.
The default is to configure PMCs to sample the CPU's instruction
pointer every 65536 events.
.It Fl o Ar outputfile
Send counter readings and textual representations of logged data
to file
.Ar outputfile .
The default is to send output to
.Pa stderr
when collecting live data and to
.Pa stdout
when processing a pre-existing logfile.
.It Fl p Ar event-spec
Allocate a process mode counting PMC measuring hardware events
specified in
.Ar event-spec .
.It Fl q
Decrease verbosity.
.It Fl r Ar fsroot
Set the top of the filesystem hierarchy under which executables
are located to argument
.Ar fsroot .
The default is
.Pa / .
.It Fl s Ar event-spec
Allocate a system mode counting PMC measuring hardware events
specified in
.Ar event-spec .
.It Fl t Ar process-spec
Attach process mode PMCs to the processes named by argument
.Ar process-spec .
Argument
.Ar process-spec
may be a non-negative integer denoting a specific process id, or a
regular expression for selecting processes based on their command names.
.It Fl v
Increase verbosity.
.It Fl w Ar secs
Print the values of all counting mode PMCs every
.Ar secs
seconds.
The argument
.Ar secs
may be a fractional value.
The default interval is 5 seconds.
.It Fl z Ar graphdepth
When printing system-wide callgraphs, limit callgraphs to the depth
specified by argument
.Ar graphdepth .
.El
.Pp
If
.Ar command
is specified, it is executed using
.Xr execvp 3 .
.Sh EXAMPLES
To perform system-wide statistical sampling on an AMD Athlon CPU with
samples taken every 32768 instruction retirals and data being sampled
to file
.Pa sample.stat ,
use:
.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
.Pp
To execute
.Nm firefox
and measure the number of data cache misses suffered
by it and its children every 12 seconds on an AMD Athlon, use:
.Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
.Pp
To measure instructions retired for all processes named
.Dq emacs
use:
.Dl "pmcstat -t '^emacs$' -p instructions"
.Pp
To measure instructions retired for processes named
.Dq emacs
for a period of 10 seconds use:
.Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
.Pp
To count instruction tlb-misses on CPUs 0 and 2 on a Intel
Pentium Pro/Pentium III SMP system use:
.Dl "pmcstat -c 0,2 -s p6-itlb-miss"
.Pp
To collect profiling information for a specific process with pid 1234
based on instruction cache misses seen by it use:
.Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
.Pp
To perform system-wide sampling on all configured processors
based on processor instructions retired use:
.Dl "pmcstat -S instructions -O /tmp/sample.out"
If callgraph capture is not desired use:
.Dl "pmcstat -N -S instructions -O /tmp/sample.out"
.Pp
To send the generated event log to a remote machine use:
.Dl "pmcstat -S instructions -O remotehost:port"
On the remote machine, the sample log can be collected using
.Xr nc 1 :
.Dl "nc -l remotehost port > /tmp/sample.out"
.Pp
To generate
.Xr gprof 1
compatible profiles from a sample file use:
.Dl "pmcstat -R /tmp/sample.out -g"
.Pp
To print a system-wide profile with callgraphs to file
.Pa "foo.graph"
use:
.Dl "pmcstat -R /tmp/sample.out -G foo.graph"
.Sh DIAGNOSTICS
If option
.Fl v
is specified,
.Nm
may issue the following diagnostic messages:
.Bl -diag -width indent
.It "#callchain/dubious-frames"
The number of callchain records that had an
.Dq impossible
value for a return address.
.It "#exec handling errors"
The number of
.Xr exec 2
events in the log file that named executables that could not be
analyzed.
.It "#exec/elf"
The number of
.Xr exec 2
events that named ELF executables.
.It "#exec/unknown"
The number of
.Xr exec 2
events that named executables with unrecognized formats.
.It "#samples/total"
The total number of samples in the log file.
.It "#samples/unclaimed"
The number of samples that could not be correlated to a known
executable object (i.e., to an executable, shared library, the
kernel or the runtime loader).
.It "#samples/unknown-object"
The number of samples that were associated with an executable
with an unrecognized object format.
.El
.Pp
.Ex -std
.Sh COMPATIBILITY
Due to the limitations of the
.Pa gmon.out
file format,
.Xr gprof 1
compatible profiles generated by the
.Fl g
option do not contain information about calls that cross executable
boundaries.
The generated
.Pa gmon.out
files are also only meaningful for native executables.
.Sh SEE ALSO
.Xr gprof 1 ,
.Xr nc 1 ,
.Xr execvp 3 ,
.Xr pmc 3 ,
.Xr pmclog 3 ,
.Xr hwpmc 4 ,
.Xr pmccontrol 8 ,
.Xr sysctl 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 6.0 .
It is
.Ud
.Sh AUTHORS
.An Joseph Koshy Aq jkoshy@FreeBSD.org
.Sh BUGS
The
.Nm
utility cannot yet analyse
.Xr hwpmc 4
logs generated by non-native architectures.
OpenPOWER on IntegriCloud