1 .\" Copyright (c) 2003-2008 Joseph Koshy
2 .\" Copyright (c) 2007 The FreeBSD Foundation
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" This software is provided by Joseph Koshy ``as is'' and
15 .\" any express or implied warranties, including, but not limited to, the
16 .\" implied warranties of merchantability and fitness for a particular purpose
17 .\" are disclaimed. in no event shall Joseph Koshy be liable
18 .\" for any direct, indirect, incidental, special, exemplary, or consequential
19 .\" damages (including, but not limited to, procurement of substitute goods
20 .\" or services; loss of use, data, or profits; or business interruption)
21 .\" however caused and on any theory of liability, whether in contract, strict
22 .\" liability, or tort (including negligence or otherwise) arising in any way
23 .\" out of the use of this software, even if advised of the possibility of
28 .Dd September 19, 2008
33 .Nd "performance measurement with performance monitoring hardware"
41 .Op Fl M Ar mapfilename
43 .Op Fl O Ar logfilename
44 .Op Fl P Ar event-spec
45 .Op Fl R Ar logfilename
46 .Op Fl S Ar event-spec
56 .Op Fl o Ar outputfile
57 .Op Fl p Ar event-spec
60 .Op Fl s Ar event-spec
61 .Op Fl t Ar process-spec
64 .Op Fl z Ar graphdepth
65 .Op Ar command Op Ar args
69 utility measures system performance using the facilities provided by
74 utility can measure both hardware events seen by the system as a
75 whole, and those seen when a specified set of processes are executing
77 If a specific set of processes is being targeted (for example,
80 option is specified, or if a command line is specified using
82 then measurement occurs till
84 exits, or till all target processes specified by the
86 options exit, or till the
88 utility is interrupted by the user.
89 If a specific set of processes is not targeted for measurement, then
91 will perform system-wide measurements till interrupted by the
96 can mix allocations of system-mode and process-mode PMCs, of both
97 counting and sampling flavors.
98 The values of all counting PMCs are printed in human readable form
99 at regular intervals by
101 The output of sampling PMCs may be configured to go to a log file for
102 subsequent offline analysis, or, at the expense of greater
103 overhead, may be configured to be printed in text form on the fly.
105 Hardware events to measure are specified to
107 using event specifier strings
109 The syntax of these event specifiers is machine dependent and is
113 A process-mode PMC may be configured to be inheritable by the target
114 process' current and future children.
116 The following options are available:
117 .Bl -tag -width indent
119 Toggle between showing cumulative or incremental counts for
120 subsequent counting mode PMCs specified on the command line.
121 The default is to show incremental counts.
123 Create files with per-program samples in the directory named
126 The default is to create these files in the current directory.
128 Toggle showing per-process counts at the time a tracked process
129 exits for subsequent process-mode PMCs specified on the command line.
130 This option is useful for mapping the performance characteristics of a
131 complex pipeline of processes when used in conjunction with the
134 The default is to not to enable per-process tracking.
136 Print calltree (Kcachegrind) information to file
142 this information is sent to the output file specified by the
146 Print callchain information to file
152 this information is sent to the output file specified by the
155 .It Fl M Ar mapfilename
156 Write the mapping between executable objects encountered in the event
157 log and the abbreviated pathnames used for
161 If this option is not specified, mapping information is not written.
166 in which case this mapping information is sent to the output
167 file configured by the
171 Toggle capturing callchain information for subsequent sampling PMCs.
172 The default is for sampling PMCs to capture callchain information.
173 .It Fl O Ar logfilename
174 Send logging output to file
179 .Ar hostname Ns : Ns Ar port ,
182 does not start with a
188 will open a network socket to host
195 option is not specified and one of the logging options is requested,
198 will print a textual form of the logged events to the configured
200 .It Fl P Ar event-spec
201 Allocate a process mode sampling PMC measuring hardware events
204 .It Fl R Ar logfilename
205 Perform offline analysis using sampling data in file
207 .It Fl S Ar event-spec
208 Allocate a system mode sampling PMC measuring hardware events
212 Use a top like mode for sampling PMCs. The following hotkeys
213 can be used: 'c+a' switch to accumulative mode, 'c+d' switch
214 to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
215 PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
218 Toggle logging the incremental counts seen by the threads of a
219 tracked process each time they are scheduled on a CPU.
220 This is an experimental feature intended to help analyse the
221 dynamic behaviour of processes in the system.
222 It may incur substantial overhead if enabled.
223 The default is for this feature to be disabled.
225 Set the cpus for subsequent system mode PMCs specified on the
230 is a comma separated list of CPU numbers, or the literal
232 denoting all unhalted CPUs.
233 The default is to allocate system mode PMCs on all unhalted
236 Toggle between process mode PMCs measuring events for the target
237 process' current and future children or only measuring events for
239 The default is to measure events for the target process alone.
240 .It Fl f Ar pluginopt
241 Pass option string to the active plugin.
243 threshold=<float> do not display cost under specified value (Top).
245 skiplink=0|1 replace node with cost under threshold by a dot (Top).
247 Produce profiles in a format compatible with
249 A separate profile file is generated for each executable object
251 Profile files are placed in sub-directories named by their PMC
253 .It Fl k Ar kerneldir
254 Set the pathname of the kernel directory to argument
256 This directory specifies where
258 should look for the kernel and its modules.
262 Print the sampled PCs with the name, the start and ending addresses
263 of the function within they live.
266 argument is mandatory and indicates where the information will be stored.
271 this information is sent to the output file specified by the
275 Set the default sampling rate for subsequent sampling mode
276 PMCs specified on the command line.
277 The default is to configure PMCs to sample the CPU's instruction
278 pointer every 65536 events.
279 .It Fl o Ar outputfile
280 Send counter readings and textual representations of logged data
283 The default is to send output to
285 when collecting live data and to
287 when processing a pre-existing logfile.
288 .It Fl p Ar event-spec
289 Allocate a process mode counting PMC measuring hardware events
295 Set the top of the filesystem hierarchy under which executables
296 are located to argument
300 .It Fl s Ar event-spec
301 Allocate a system mode counting PMC measuring hardware events
304 .It Fl t Ar process-spec
305 Attach process mode PMCs to the processes named by argument
309 may be a non-negative integer denoting a specific process id, or a
310 regular expression for selecting processes based on their command names.
314 Print the values of all counting mode PMCs or sampling mode PMCs
320 may be a fractional value.
321 The default interval is 5 seconds.
322 .It Fl z Ar graphdepth
323 When printing system-wide callgraphs, limit callgraphs to the depth
324 specified by argument
330 is specified, it is executed using
333 To perform system-wide statistical sampling on an AMD Athlon CPU with
334 samples taken every 32768 instruction retirals and data being sampled
338 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
342 and measure the number of data cache misses suffered
343 by it and its children every 12 seconds on an AMD Athlon, use:
344 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
346 To measure instructions retired for all processes named
349 .Dl "pmcstat -t '^emacs$' -p instructions"
351 To measure instructions retired for processes named
353 for a period of 10 seconds use:
354 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
356 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
357 Pentium Pro/Pentium III SMP system use:
358 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
360 To collect profiling information for a specific process with pid 1234
361 based on instruction cache misses seen by it use:
362 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
364 To perform system-wide sampling on all configured processors
365 based on processor instructions retired use:
366 .Dl "pmcstat -S instructions -O /tmp/sample.out"
367 If callgraph capture is not desired use:
368 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
370 To send the generated event log to a remote machine use:
371 .Dl "pmcstat -S instructions -O remotehost:port"
372 On the remote machine, the sample log can be collected using
374 .Dl "nc -l remotehost port > /tmp/sample.out"
378 compatible profiles from a sample file use:
379 .Dl "pmcstat -R /tmp/sample.out -g"
381 To print a system-wide profile with callgraphs to file
384 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
390 may issue the following diagnostic messages:
392 .It "#callchain/dubious-frames"
393 The number of callchain records that had an
395 value for a return address.
396 .It "#exec handling errors"
399 events in the log file that named executables that could not be
404 events that named ELF executables.
408 events that named executables with unrecognized formats.
410 The total number of samples in the log file.
411 .It "#samples/unclaimed"
412 The number of samples that could not be correlated to a known
413 executable object (i.e., to an executable, shared library, the
414 kernel or the runtime loader).
415 .It "#samples/unknown-object"
416 The number of samples that were associated with an executable
417 with an unrecognized object format.
422 Due to the limitations of the
426 compatible profiles generated by the
428 option do not contain information about calls that cross executable
432 files are also only meaningful for native executables.
445 utility first appeared in
450 .An Joseph Koshy Aq jkoshy@FreeBSD.org
454 utility cannot yet analyse
456 logs generated by non-native architectures.