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"
43 .Op Fl M Ar mapfilename
45 .Op Fl O Ar logfilename
46 .Op Fl P Ar event-spec
47 .Op Fl R Ar logfilename
48 .Op Fl S Ar event-spec
63 .Op Fl o Ar outputfile
64 .Op Fl p Ar event-spec
67 .Op Fl s Ar event-spec
68 .Op Fl t Ar process-spec
69 .Op Fl u Ar event-spec
72 .Op Fl z Ar graphdepth
73 .Op Ar command Op Ar args
77 utility measures system performance using the facilities provided by
82 utility can measure both hardware events seen by the system as a
83 whole, and those seen when a specified set of processes are executing
85 If a specific set of processes is being targeted (for example,
88 option is specified, or if a command line is specified using
90 then measurement occurs till
92 exits, or till all target processes specified by the
94 options exit, or till the
96 utility is interrupted by the user.
97 If a specific set of processes is not targeted for measurement, then
99 will perform system-wide measurements till interrupted by the
102 A given invocation of
104 can mix allocations of system-mode and process-mode PMCs, of both
105 counting and sampling flavors.
106 The values of all counting PMCs are printed in human readable form
107 at regular intervals by
109 The output of sampling PMCs may be configured to go to a log file for
110 subsequent offline analysis, or, at the expense of greater
111 overhead, may be configured to be printed in text form on the fly.
113 Hardware events to measure are specified to
115 using event specifier strings
117 The syntax of these event specifiers is machine dependent and is
121 A process-mode PMC may be configured to be inheritable by the target
122 process' current and future children.
124 The following options are available:
125 .Bl -tag -width indent
127 Toggle between showing cumulative or incremental counts for
128 subsequent counting mode PMCs specified on the command line.
129 The default is to show incremental counts.
131 Create files with per-program samples in the directory named
134 The default is to create these files in the current directory.
136 Toggle showing per-process counts at the time a tracked process
137 exits for subsequent process-mode PMCs specified on the command line.
138 This option is useful for mapping the performance characteristics of a
139 complex pipeline of processes when used in conjunction with the
142 The default is to not to enable per-process tracking.
144 Print calltree (Kcachegrind) information to file
150 this information is sent to the output file specified by the
154 Print callchain information to file
160 this information is sent to the output file specified by the
164 Skip symbol lookup and display address instead.
166 List all event names.
167 .It Fl M Ar mapfilename
168 Write the mapping between executable objects encountered in the event
169 log and the abbreviated pathnames used for
173 If this option is not specified, mapping information is not written.
178 in which case this mapping information is sent to the output
179 file configured by the
183 Toggle capturing callchain information for subsequent sampling PMCs.
184 The default is for sampling PMCs to capture callchain information.
185 .It Fl O Ar logfilename
186 Send logging output to file
191 .Ar hostname Ns : Ns Ar port ,
194 does not start with a
200 will open a network socket to host
207 option is not specified and one of the logging options is requested,
210 will print a textual form of the logged events to the configured
212 .It Fl P Ar event-spec
213 Allocate a process mode sampling PMC measuring hardware events
216 .It Fl R Ar logfilename
217 Perform offline analysis using sampling data in file
219 .It Fl S Ar event-spec
220 Allocate a system mode sampling PMC measuring hardware events
224 Use a top like mode for sampling PMCs. The following hotkeys
225 can be used: 'c+a' switch to accumulative mode, 'c+d' switch
226 to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
227 PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
230 Toggle capturing user-space call traces while in kernel mode.
231 The default is for sampling PMCs to capture user-space callchain information
232 while in user-space mode, and kernel callchain information while in kernel mode.
234 Toggle logging the incremental counts seen by the threads of a
235 tracked process each time they are scheduled on a CPU.
236 This is an experimental feature intended to help analyse the
237 dynamic behaviour of processes in the system.
238 It may incur substantial overhead if enabled.
239 The default is for this feature to be disabled.
241 Perform a symbol and file:line lookup for each address in each
242 callgraph and save the output to
246 that only resolves the first symbol in the graph, this resolves
247 every node in the callgraph, or prints out addresses if no
248 lookup information is available.
249 This option requires the
251 option to read in samples that were previously collected and
256 Set the cpus for subsequent system mode PMCs specified on the
261 is a comma separated list of CPU numbers, or the literal
263 denoting all available CPUs.
264 The default is to allocate system mode PMCs on all available
267 Toggle between process mode PMCs measuring events for the target
268 process' current and future children or only measuring events for
270 The default is to measure events for the target process alone.
271 (it has to be passed in the command line prior to
278 Specify that the gprof profile files will use a wide history counter.
279 These files are produced in a format compatible with
281 However, other tools that cannot fully parse a BSD-style
282 gmon header might be unable to correctly parse these files.
283 .It Fl f Ar pluginopt
284 Pass option string to the active plugin.
286 threshold=<float> do not display cost under specified value (Top).
288 skiplink=0|1 replace node with cost under threshold by a dot (Top).
290 Produce profiles in a format compatible with
292 A separate profile file is generated for each executable object
294 Profile files are placed in sub-directories named by their PMC
299 which you can get from
303 .It Fl k Ar kerneldir
304 Set the pathname of the kernel directory to argument
306 This directory specifies where
308 should look for the kernel and its modules.
309 The default is to use the path of the running kernel obtained from the
313 Set system-wide performance measurement duration for
318 may be a fractional value.
320 Print the sampled PCs with the name, the start and ending addresses
321 of the function within they live.
324 argument is mandatory and indicates where the information will be stored.
329 this information is sent to the output file specified by the
332 This option requires the
334 option to read in samples that were previously collected and
339 Set the default sampling rate for subsequent sampling mode
340 PMCs specified on the command line.
341 The default is to configure PMCs to sample the CPU's instruction
342 pointer every 65536 events.
343 .It Fl o Ar outputfile
344 Send counter readings and textual representations of logged data
347 The default is to send output to
349 when collecting live data and to
351 when processing a pre-existing logfile.
352 .It Fl p Ar event-spec
353 Allocate a process mode counting PMC measuring hardware events
359 Set the top of the filesystem hierarchy under which executables
360 are located to argument
364 .It Fl s Ar event-spec
365 Allocate a system mode counting PMC measuring hardware events
368 .It Fl t Ar process-spec
369 Attach process mode PMCs to the processes named by argument
373 may be a non-negative integer denoting a specific process id, or a
374 regular expression for selecting processes based on their command names.
375 .It Fl u Ar event-spec
376 Provide short description of event.
380 Print the values of all counting mode PMCs or sampling mode PMCs
386 may be a fractional value.
387 The default interval is 5 seconds.
388 .It Fl z Ar graphdepth
389 When printing system-wide callgraphs, limit callgraphs to the depth
390 specified by argument
396 is specified, it is executed using
399 To perform system-wide statistical sampling on an AMD Athlon CPU with
400 samples taken every 32768 instruction retirals and data being sampled
404 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
408 and measure the number of data cache misses suffered
409 by it and its children every 12 seconds on an AMD Athlon, use:
410 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
412 To measure instructions retired for all processes named
415 .Dl "pmcstat -t '^emacs$' -p instructions"
417 To measure instructions retired for processes named
419 for a period of 10 seconds use:
420 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
422 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
423 Pentium Pro/Pentium III SMP system use:
424 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
426 To collect profiling information for a specific process with pid 1234
427 based on instruction cache misses seen by it use:
428 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
430 To perform system-wide sampling on all configured processors
431 based on processor instructions retired use:
432 .Dl "pmcstat -S instructions -O /tmp/sample.out"
433 If callgraph capture is not desired use:
434 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
436 To send the generated event log to a remote machine use:
437 .Dl "pmcstat -S instructions -O remotehost:port"
438 On the remote machine, the sample log can be collected using
440 .Dl "nc -l remotehost port > /tmp/sample.out"
444 compatible profiles from a sample file use:
445 .Dl "pmcstat -R /tmp/sample.out -g"
447 To print a system-wide profile with callgraphs to file
450 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
456 may issue the following diagnostic messages:
458 .It "#callchain/dubious-frames"
459 The number of callchain records that had an
461 value for a return address.
462 .It "#exec handling errors"
465 events in the log file that named executables that could not be
470 events that named ELF executables.
474 events that named executables with unrecognized formats.
476 The total number of samples in the log file.
477 .It "#samples/unclaimed"
478 The number of samples that could not be correlated to a known
479 executable object (i.e., to an executable, shared library, the
480 kernel or the runtime loader).
481 .It "#samples/unknown-object"
482 The number of samples that were associated with an executable
483 with an unrecognized object format.
488 Due to the limitations of the
492 compatible profiles generated by the
494 option do not contain information about calls that cross executable
498 files are also only meaningful for native executables.
511 utility first appeared in
516 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org
520 utility cannot yet analyse
522 logs generated by non-native architectures.
projects / FreeBSD / FreeBSD.git / blob