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
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
58 .Op Fl o Ar outputfile
59 .Op Fl p Ar event-spec
62 .Op Fl s Ar event-spec
63 .Op Fl t Ar process-spec
66 .Op Fl z Ar graphdepth
67 .Op Ar command Op Ar args
71 utility measures system performance using the facilities provided by
76 utility can measure both hardware events seen by the system as a
77 whole, and those seen when a specified set of processes are executing
79 If a specific set of processes is being targeted (for example,
82 option is specified, or if a command line is specified using
84 then measurement occurs till
86 exits, or till all target processes specified by the
88 options exit, or till the
90 utility is interrupted by the user.
91 If a specific set of processes is not targeted for measurement, then
93 will perform system-wide measurements till interrupted by the
98 can mix allocations of system-mode and process-mode PMCs, of both
99 counting and sampling flavors.
100 The values of all counting PMCs are printed in human readable form
101 at regular intervals by
103 The output of sampling PMCs may be configured to go to a log file for
104 subsequent offline analysis, or, at the expense of greater
105 overhead, may be configured to be printed in text form on the fly.
107 Hardware events to measure are specified to
109 using event specifier strings
111 The syntax of these event specifiers is machine dependent and is
115 A process-mode PMC may be configured to be inheritable by the target
116 process' current and future children.
118 The following options are available:
119 .Bl -tag -width indent
121 Toggle between showing cumulative or incremental counts for
122 subsequent counting mode PMCs specified on the command line.
123 The default is to show incremental counts.
125 Create files with per-program samples in the directory named
128 The default is to create these files in the current directory.
130 Toggle showing per-process counts at the time a tracked process
131 exits for subsequent process-mode PMCs specified on the command line.
132 This option is useful for mapping the performance characteristics of a
133 complex pipeline of processes when used in conjunction with the
136 The default is to not to enable per-process tracking.
138 Print calltree (Kcachegrind) information to file
144 this information is sent to the output file specified by the
148 Print callchain information to file
154 this information is sent to the output file specified by the
157 .It Fl M Ar mapfilename
158 Write the mapping between executable objects encountered in the event
159 log and the abbreviated pathnames used for
163 If this option is not specified, mapping information is not written.
168 in which case this mapping information is sent to the output
169 file configured by the
173 Toggle capturing callchain information for subsequent sampling PMCs.
174 The default is for sampling PMCs to capture callchain information.
175 .It Fl O Ar logfilename
176 Send logging output to file
181 .Ar hostname Ns : Ns Ar port ,
184 does not start with a
190 will open a network socket to host
197 option is not specified and one of the logging options is requested,
200 will print a textual form of the logged events to the configured
202 .It Fl P Ar event-spec
203 Allocate a process mode sampling PMC measuring hardware events
206 .It Fl R Ar logfilename
207 Perform offline analysis using sampling data in file
209 .It Fl S Ar event-spec
210 Allocate a system mode sampling PMC measuring hardware events
214 Use a top like mode for sampling PMCs. The following hotkeys
215 can be used: 'c+a' switch to accumulative mode, 'c+d' switch
216 to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
217 PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
220 Toggle logging the incremental counts seen by the threads of a
221 tracked process each time they are scheduled on a CPU.
222 This is an experimental feature intended to help analyse the
223 dynamic behaviour of processes in the system.
224 It may incur substantial overhead if enabled.
225 The default is for this feature to be disabled.
227 Perform a symbol and file:line lookup for each address in each
228 callgraph and save the output to
232 that only resolves the first symbol in the graph, this resolves
233 every node in the callgraph, or prints out addresses if no
234 lookup information is available.
235 This option requires the
237 option to read in samples that were previously collected and
242 Set the cpus for subsequent system mode PMCs specified on the
247 is a comma separated list of CPU numbers, or the literal
249 denoting all available CPUs.
250 The default is to allocate system mode PMCs on all available
253 Toggle between process mode PMCs measuring events for the target
254 process' current and future children or only measuring events for
256 The default is to measure events for the target process alone.
257 (it has to be passed in the command line prior to
263 .It Fl f Ar pluginopt
264 Pass option string to the active plugin.
266 threshold=<float> do not display cost under specified value (Top).
268 skiplink=0|1 replace node with cost under threshold by a dot (Top).
270 Produce profiles in a format compatible with
272 A separate profile file is generated for each executable object
274 Profile files are placed in sub-directories named by their PMC
276 .It Fl k Ar kerneldir
277 Set the pathname of the kernel directory to argument
279 This directory specifies where
281 should look for the kernel and its modules.
282 The default is to use the path of the running kernel obtained from the
286 Set system-wide performance measurement duration for
291 may be a fractional value.
293 Print the sampled PCs with the name, the start and ending addresses
294 of the function within they live.
297 argument is mandatory and indicates where the information will be stored.
302 this information is sent to the output file specified by the
305 This option requires the
307 option to read in samples that were previously collected and
312 Set the default sampling rate for subsequent sampling mode
313 PMCs specified on the command line.
314 The default is to configure PMCs to sample the CPU's instruction
315 pointer every 65536 events.
316 .It Fl o Ar outputfile
317 Send counter readings and textual representations of logged data
320 The default is to send output to
322 when collecting live data and to
324 when processing a pre-existing logfile.
325 .It Fl p Ar event-spec
326 Allocate a process mode counting PMC measuring hardware events
332 Set the top of the filesystem hierarchy under which executables
333 are located to argument
337 .It Fl s Ar event-spec
338 Allocate a system mode counting PMC measuring hardware events
341 .It Fl t Ar process-spec
342 Attach process mode PMCs to the processes named by argument
346 may be a non-negative integer denoting a specific process id, or a
347 regular expression for selecting processes based on their command names.
351 Print the values of all counting mode PMCs or sampling mode PMCs
357 may be a fractional value.
358 The default interval is 5 seconds.
359 .It Fl z Ar graphdepth
360 When printing system-wide callgraphs, limit callgraphs to the depth
361 specified by argument
367 is specified, it is executed using
370 To perform system-wide statistical sampling on an AMD Athlon CPU with
371 samples taken every 32768 instruction retirals and data being sampled
375 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
379 and measure the number of data cache misses suffered
380 by it and its children every 12 seconds on an AMD Athlon, use:
381 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
383 To measure instructions retired for all processes named
386 .Dl "pmcstat -t '^emacs$' -p instructions"
388 To measure instructions retired for processes named
390 for a period of 10 seconds use:
391 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
393 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
394 Pentium Pro/Pentium III SMP system use:
395 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
397 To collect profiling information for a specific process with pid 1234
398 based on instruction cache misses seen by it use:
399 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
401 To perform system-wide sampling on all configured processors
402 based on processor instructions retired use:
403 .Dl "pmcstat -S instructions -O /tmp/sample.out"
404 If callgraph capture is not desired use:
405 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
407 To send the generated event log to a remote machine use:
408 .Dl "pmcstat -S instructions -O remotehost:port"
409 On the remote machine, the sample log can be collected using
411 .Dl "nc -l remotehost port > /tmp/sample.out"
415 compatible profiles from a sample file use:
416 .Dl "pmcstat -R /tmp/sample.out -g"
418 To print a system-wide profile with callgraphs to file
421 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
427 may issue the following diagnostic messages:
429 .It "#callchain/dubious-frames"
430 The number of callchain records that had an
432 value for a return address.
433 .It "#exec handling errors"
436 events in the log file that named executables that could not be
441 events that named ELF executables.
445 events that named executables with unrecognized formats.
447 The total number of samples in the log file.
448 .It "#samples/unclaimed"
449 The number of samples that could not be correlated to a known
450 executable object (i.e., to an executable, shared library, the
451 kernel or the runtime loader).
452 .It "#samples/unknown-object"
453 The number of samples that were associated with an executable
454 with an unrecognized object format.
459 Due to the limitations of the
463 compatible profiles generated by the
465 option do not contain information about calls that cross executable
469 files are also only meaningful for native executables.
482 utility first appeared in
487 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org
491 utility cannot yet analyse
493 logs generated by non-native architectures.
projects / FreeBSD / FreeBSD.git / blob