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"
44 .Op Fl M Ar mapfilename
46 .Op Fl O Ar logfilename
47 .Op Fl P Ar event-spec
48 .Op Fl R Ar logfilename
49 .Op Fl S Ar event-spec
64 .Op Fl o Ar outputfile
65 .Op Fl p Ar event-spec
68 .Op Fl s Ar event-spec
69 .Op Fl t Ar process-spec
70 .Op Fl u Ar event-spec
73 .Op Fl z Ar graphdepth
74 .Op Ar command Op Ar args
78 utility measures system performance using the facilities provided by
83 utility can measure both hardware events seen by the system as a
84 whole, and those seen when a specified set of processes are executing
86 If a specific set of processes is being targeted (for example,
89 option is specified, or if a command line is specified using
91 then measurement occurs till
93 exits, or till all target processes specified by the
95 options exit, or till the
97 utility is interrupted by the user.
98 If a specific set of processes is not targeted for measurement, then
100 will perform system-wide measurements till interrupted by the
103 A given invocation of
105 can mix allocations of system-mode and process-mode PMCs, of both
106 counting and sampling flavors.
107 The values of all counting PMCs are printed in human readable form
108 at regular intervals by
110 The output of sampling PMCs may be configured to go to a log file for
111 subsequent offline analysis, or, at the expense of greater
112 overhead, may be configured to be printed in text form on the fly.
114 Hardware events to measure are specified to
116 using event specifier strings
118 The syntax of these event specifiers is machine dependent and is
122 A process-mode PMC may be configured to be inheritable by the target
123 process' current and future children.
125 The following options are available:
126 .Bl -tag -width indent
128 Skip symbol lookup and display address instead.
130 Toggle between showing cumulative or incremental counts for
131 subsequent counting mode PMCs specified on the command line.
132 The default is to show incremental counts.
134 Create files with per-program samples in the directory named
137 The default is to create these files in the current directory.
139 Toggle showing per-process counts at the time a tracked process
140 exits for subsequent process-mode PMCs specified on the command line.
141 This option is useful for mapping the performance characteristics of a
142 complex pipeline of processes when used in conjunction with the
145 The default is to not to enable per-process tracking.
147 Print calltree (Kcachegrind) information to file
153 this information is sent to the output file specified by the
157 Print callchain information to file
163 this information is sent to the output file specified by the
167 Show the offset of the instruction pointer into the symbol.
169 List all event names.
170 .It Fl M Ar mapfilename
171 Write the mapping between executable objects encountered in the event
172 log and the abbreviated pathnames used for
176 If this option is not specified, mapping information is not written.
181 in which case this mapping information is sent to the output
182 file configured by the
186 Toggle capturing callchain information for subsequent sampling PMCs.
187 The default is for sampling PMCs to capture callchain information.
188 .It Fl O Ar logfilename
189 Send logging output to file
194 .Ar hostname Ns : Ns Ar port ,
197 does not start with a
203 will open a network socket to host
210 option is not specified and one of the logging options is requested,
213 will print a textual form of the logged events to the configured
215 .It Fl P Ar event-spec
216 Allocate a process mode sampling PMC measuring hardware events
219 .It Fl R Ar logfilename
220 Perform offline analysis using sampling data in file
222 .It Fl S Ar event-spec
223 Allocate a system mode sampling PMC measuring hardware events
227 Use a top like mode for sampling PMCs. The following hotkeys
228 can be used: 'A' toggle symbol resolution, 'c+a' switch to accumulative mode, 'c+d'
229 switch to delta mode, 'I' toggle showing offsets into symbols, 'm' merge PMCs, 'n'
230 change view, 'p' show next PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under
231 threshold is seen as a dot.
233 Toggle capturing user-space call traces while in kernel mode.
234 The default is for sampling PMCs to capture user-space callchain information
235 while in user-space mode, and kernel callchain information while in kernel mode.
237 Toggle logging the incremental counts seen by the threads of a
238 tracked process each time they are scheduled on a CPU.
239 This is an experimental feature intended to help analyse the
240 dynamic behaviour of processes in the system.
241 It may incur substantial overhead if enabled.
242 The default is for this feature to be disabled.
244 Perform a symbol and file:line lookup for each address in each
245 callgraph and save the output to
249 that only resolves the first symbol in the graph, this resolves
250 every node in the callgraph, or prints out addresses if no
251 lookup information is available.
252 This option requires the
254 option to read in samples that were previously collected and
259 Set the cpus for subsequent system mode PMCs specified on the
264 is a comma separated list of CPU numbers, or the literal
266 denoting all available CPUs.
267 The default is to allocate system mode PMCs on all available
270 Toggle between process mode PMCs measuring events for the target
271 process' current and future children or only measuring events for
273 The default is to measure events for the target process alone.
274 (it has to be passed in the command line prior to
281 Specify that the gprof profile files will use a wide history counter.
282 These files are produced in a format compatible with
284 However, other tools that cannot fully parse a BSD-style
285 gmon header might be unable to correctly parse these files.
286 .It Fl f Ar pluginopt
287 Pass option string to the active plugin.
289 threshold=<float> do not display cost under specified value (Top).
291 skiplink=0|1 replace node with cost under threshold by a dot (Top).
293 Produce profiles in a format compatible with
295 A separate profile file is generated for each executable object
297 Profile files are placed in sub-directories named by their PMC
302 which you can get from
306 .It Fl k Ar kerneldir
307 Set the pathname of the kernel directory to argument
309 This directory specifies where
311 should look for the kernel and its modules.
312 The default is to use the path of the running kernel obtained from the
315 Modules will also be searched for in /boot/modules if not found in
318 Set system-wide performance measurement duration for
323 may be a fractional value.
325 Print the sampled PCs with the name, the start and ending addresses
326 of the function within they live.
329 argument is mandatory and indicates where the information will be stored.
334 this information is sent to the output file specified by the
337 This option requires the
339 option to read in samples that were previously collected and
344 Set the default sampling rate for subsequent sampling mode
345 PMCs specified on the command line.
346 The default is to configure PMCs to sample the CPU's instruction
347 pointer every 65536 events.
348 .It Fl o Ar outputfile
349 Send counter readings and textual representations of logged data
352 The default is to send output to
354 when collecting live data and to
356 when processing a pre-existing logfile.
357 .It Fl p Ar event-spec
358 Allocate a process mode counting PMC measuring hardware events
364 Set the top of the filesystem hierarchy under which executables
365 are located to argument
369 .It Fl s Ar event-spec
370 Allocate a system mode counting PMC measuring hardware events
373 .It Fl t Ar process-spec
374 Attach process mode PMCs to the processes named by argument
378 may be a non-negative integer denoting a specific process id, or a
379 regular expression for selecting processes based on their command names.
380 .It Fl u Ar event-spec
381 Provide short description of event.
385 Print the values of all counting mode PMCs or sampling mode PMCs
391 may be a fractional value.
392 The default interval is 5 seconds.
393 .It Fl z Ar graphdepth
394 When printing system-wide callgraphs, limit callgraphs to the depth
395 specified by argument
401 is specified, it is executed using
404 To perform system-wide statistical sampling on an AMD Athlon CPU with
405 samples taken every 32768 instruction retirals and data being sampled
409 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
413 and measure the number of data cache misses suffered
414 by it and its children every 12 seconds on an AMD Athlon, use:
415 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
417 To measure instructions retired for all processes named
420 .Dl "pmcstat -t '^emacs$' -p instructions"
422 To measure instructions retired for processes named
424 for a period of 10 seconds use:
425 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
427 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
428 Pentium Pro/Pentium III SMP system use:
429 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
431 To collect profiling information for a specific process with pid 1234
432 based on instruction cache misses seen by it use:
433 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
435 To perform system-wide sampling on all configured processors
436 based on processor instructions retired use:
437 .Dl "pmcstat -S instructions -O /tmp/sample.out"
438 If callgraph capture is not desired use:
439 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
441 To send the generated event log to a remote machine use:
442 .Dl "pmcstat -S instructions -O remotehost:port"
443 On the remote machine, the sample log can be collected using
445 .Dl "nc -l remotehost port > /tmp/sample.out"
449 compatible profiles from a sample file use:
450 .Dl "pmcstat -R /tmp/sample.out -g"
452 To print a system-wide profile with callgraphs to file
455 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
461 may issue the following diagnostic messages:
463 .It "#callchain/dubious-frames"
464 The number of callchain records that had an
466 value for a return address.
467 .It "#exec handling errors"
470 events in the log file that named executables that could not be
475 events that named ELF executables.
479 events that named executables with unrecognized formats.
481 The total number of samples in the log file.
482 .It "#samples/unclaimed"
483 The number of samples that could not be correlated to a known
484 executable object (i.e., to an executable, shared library, the
485 kernel or the runtime loader).
486 .It "#samples/unknown-object"
487 The number of samples that were associated with an executable
488 with an unrecognized object format.
493 Due to the limitations of the
497 compatible profiles generated by the
499 option do not contain information about calls that cross executable
503 files are also only meaningful for native executables.
516 utility first appeared in
521 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org
525 utility cannot yet analyse
527 logs generated by non-native architectures.
projects / FreeBSD / FreeBSD.git / blob