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
59 .Op Fl o Ar outputfile
60 .Op Fl p Ar event-spec
63 .Op Fl s Ar event-spec
64 .Op Fl t Ar process-spec
67 .Op Fl z Ar graphdepth
68 .Op Ar command Op Ar args
72 utility measures system performance using the facilities provided by
77 utility can measure both hardware events seen by the system as a
78 whole, and those seen when a specified set of processes are executing
80 If a specific set of processes is being targeted (for example,
83 option is specified, or if a command line is specified using
85 then measurement occurs till
87 exits, or till all target processes specified by the
89 options exit, or till the
91 utility is interrupted by the user.
92 If a specific set of processes is not targeted for measurement, then
94 will perform system-wide measurements till interrupted by the
99 can mix allocations of system-mode and process-mode PMCs, of both
100 counting and sampling flavors.
101 The values of all counting PMCs are printed in human readable form
102 at regular intervals by
104 The output of sampling PMCs may be configured to go to a log file for
105 subsequent offline analysis, or, at the expense of greater
106 overhead, may be configured to be printed in text form on the fly.
108 Hardware events to measure are specified to
110 using event specifier strings
112 The syntax of these event specifiers is machine dependent and is
116 A process-mode PMC may be configured to be inheritable by the target
117 process' current and future children.
119 The following options are available:
120 .Bl -tag -width indent
122 Toggle between showing cumulative or incremental counts for
123 subsequent counting mode PMCs specified on the command line.
124 The default is to show incremental counts.
126 Create files with per-program samples in the directory named
129 The default is to create these files in the current directory.
131 Toggle showing per-process counts at the time a tracked process
132 exits for subsequent process-mode PMCs specified on the command line.
133 This option is useful for mapping the performance characteristics of a
134 complex pipeline of processes when used in conjunction with the
137 The default is to not to enable per-process tracking.
139 Print calltree (Kcachegrind) information to file
145 this information is sent to the output file specified by the
149 Print callchain information to file
155 this information is sent to the output file specified by the
158 .It Fl M Ar mapfilename
159 Write the mapping between executable objects encountered in the event
160 log and the abbreviated pathnames used for
164 If this option is not specified, mapping information is not written.
169 in which case this mapping information is sent to the output
170 file configured by the
174 Toggle capturing callchain information for subsequent sampling PMCs.
175 The default is for sampling PMCs to capture callchain information.
176 .It Fl O Ar logfilename
177 Send logging output to file
182 .Ar hostname Ns : Ns Ar port ,
185 does not start with a
191 will open a network socket to host
198 option is not specified and one of the logging options is requested,
201 will print a textual form of the logged events to the configured
203 .It Fl P Ar event-spec
204 Allocate a process mode sampling PMC measuring hardware events
207 .It Fl R Ar logfilename
208 Perform offline analysis using sampling data in file
210 .It Fl S Ar event-spec
211 Allocate a system mode sampling PMC measuring hardware events
215 Use a top like mode for sampling PMCs. The following hotkeys
216 can be used: 'c+a' switch to accumulative mode, 'c+d' switch
217 to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
218 PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
221 Toggle logging the incremental counts seen by the threads of a
222 tracked process each time they are scheduled on a CPU.
223 This is an experimental feature intended to help analyse the
224 dynamic behaviour of processes in the system.
225 It may incur substantial overhead if enabled.
226 The default is for this feature to be disabled.
228 Perform a symbol and file:line lookup for each address in each
229 callgraph and save the output to
233 that only resolves the first symbol in the graph, this resolves
234 every node in the callgraph, or prints out addresses if no
235 lookup information is available.
236 This option requires the
238 option to read in samples that were previously collected and
243 Set the cpus for subsequent system mode PMCs specified on the
248 is a comma separated list of CPU numbers, or the literal
250 denoting all available CPUs.
251 The default is to allocate system mode PMCs on all available
254 Toggle between process mode PMCs measuring events for the target
255 process' current and future children or only measuring events for
257 The default is to measure events for the target process alone.
258 (it has to be passed in the command line prior to
265 Specify that the gprof profile files will use a wide history counter.
266 These files are produced in a format compatible with
268 However, other tools that cannot fully parse a BSD-style
269 gmon header might be unable to correctly parse these files.
270 .It Fl f Ar pluginopt
271 Pass option string to the active plugin.
273 threshold=<float> do not display cost under specified value (Top).
275 skiplink=0|1 replace node with cost under threshold by a dot (Top).
277 Produce profiles in a format compatible with
279 A separate profile file is generated for each executable object
281 Profile files are placed in sub-directories named by their PMC
283 .It Fl k Ar kerneldir
284 Set the pathname of the kernel directory to argument
286 This directory specifies where
288 should look for the kernel and its modules.
289 The default is to use the path of the running kernel obtained from the
293 Set system-wide performance measurement duration for
298 may be a fractional value.
300 Print the sampled PCs with the name, the start and ending addresses
301 of the function within they live.
304 argument is mandatory and indicates where the information will be stored.
309 this information is sent to the output file specified by the
312 This option requires the
314 option to read in samples that were previously collected and
319 Set the default sampling rate for subsequent sampling mode
320 PMCs specified on the command line.
321 The default is to configure PMCs to sample the CPU's instruction
322 pointer every 65536 events.
323 .It Fl o Ar outputfile
324 Send counter readings and textual representations of logged data
327 The default is to send output to
329 when collecting live data and to
331 when processing a pre-existing logfile.
332 .It Fl p Ar event-spec
333 Allocate a process mode counting PMC measuring hardware events
339 Set the top of the filesystem hierarchy under which executables
340 are located to argument
344 .It Fl s Ar event-spec
345 Allocate a system mode counting PMC measuring hardware events
348 .It Fl t Ar process-spec
349 Attach process mode PMCs to the processes named by argument
353 may be a non-negative integer denoting a specific process id, or a
354 regular expression for selecting processes based on their command names.
358 Print the values of all counting mode PMCs or sampling mode PMCs
364 may be a fractional value.
365 The default interval is 5 seconds.
366 .It Fl z Ar graphdepth
367 When printing system-wide callgraphs, limit callgraphs to the depth
368 specified by argument
374 is specified, it is executed using
377 To perform system-wide statistical sampling on an AMD Athlon CPU with
378 samples taken every 32768 instruction retirals and data being sampled
382 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
386 and measure the number of data cache misses suffered
387 by it and its children every 12 seconds on an AMD Athlon, use:
388 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
390 To measure instructions retired for all processes named
393 .Dl "pmcstat -t '^emacs$' -p instructions"
395 To measure instructions retired for processes named
397 for a period of 10 seconds use:
398 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
400 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
401 Pentium Pro/Pentium III SMP system use:
402 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
404 To collect profiling information for a specific process with pid 1234
405 based on instruction cache misses seen by it use:
406 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
408 To perform system-wide sampling on all configured processors
409 based on processor instructions retired use:
410 .Dl "pmcstat -S instructions -O /tmp/sample.out"
411 If callgraph capture is not desired use:
412 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
414 To send the generated event log to a remote machine use:
415 .Dl "pmcstat -S instructions -O remotehost:port"
416 On the remote machine, the sample log can be collected using
418 .Dl "nc -l remotehost port > /tmp/sample.out"
422 compatible profiles from a sample file use:
423 .Dl "pmcstat -R /tmp/sample.out -g"
425 To print a system-wide profile with callgraphs to file
428 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
434 may issue the following diagnostic messages:
436 .It "#callchain/dubious-frames"
437 The number of callchain records that had an
439 value for a return address.
440 .It "#exec handling errors"
443 events in the log file that named executables that could not be
448 events that named ELF executables.
452 events that named executables with unrecognized formats.
454 The total number of samples in the log file.
455 .It "#samples/unclaimed"
456 The number of samples that could not be correlated to a known
457 executable object (i.e., to an executable, shared library, the
458 kernel or the runtime loader).
459 .It "#samples/unknown-object"
460 The number of samples that were associated with an executable
461 with an unrecognized object format.
466 Due to the limitations of the
470 compatible profiles generated by the
472 option do not contain information about calls that cross executable
476 files are also only meaningful for native executables.
489 utility first appeared in
494 .An Joseph Koshy Aq jkoshy@FreeBSD.org
498 utility cannot yet analyse
500 logs generated by non-native architectures.
projects / FreeBSD / stable / 10.git / blob