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"
40 .Op Fl M Ar mapfilename
42 .Op Fl O Ar logfilename
43 .Op Fl P Ar event-spec
44 .Op Fl R Ar logfilename
45 .Op Fl S Ar event-spec
53 .Op Fl o Ar outputfile
54 .Op Fl p Ar event-spec
57 .Op Fl s Ar event-spec
58 .Op Fl t Ar process-spec
61 .Op Fl z Ar graphdepth
62 .Op Ar command Op Ar args
66 utility measures system performance using the facilities provided by
71 utility can measure both hardware events seen by the system as a
72 whole, and those seen when a specified set of processes are executing
74 If a specific set of processes is being targeted (for example,
77 option is specified, or if a command line is specified using
79 then measurement occurs till
81 exits, or till all target processes specified by the
83 options exit, or till the
85 utility is interrupted by the user.
86 If a specific set of processes is not targeted for measurement, then
88 will perform system-wide measurements till interrupted by the
93 can mix allocations of system-mode and process-mode PMCs, of both
94 counting and sampling flavors.
95 The values of all counting PMCs are printed in human readable form
96 at regular intervals by
98 The output of sampling PMCs may be configured to go to a log file for
99 subsequent offline analysis, or, at the expense of greater
100 overhead, may be configured to be printed in text form on the fly.
102 Hardware events to measure are specified to
104 using event specifier strings
106 The syntax of these event specifiers is machine dependent and is
110 A process-mode PMC may be configured to be inheritable by the target
111 process' current and future children.
113 The following options are available:
114 .Bl -tag -width indent
116 Toggle between showing cumulative or incremental counts for
117 subsequent counting mode PMCs specified on the command line.
118 The default is to show incremental counts.
120 Create files with per-program samples in the directory named
123 The default is to create these files in the current directory.
125 Toggle showing per-process counts at the time a tracked process
126 exits for subsequent process-mode PMCs specified on the command line.
127 This option is useful for mapping the performance characteristics of a
128 complex pipeline of processes when used in conjunction with the
131 The default is to not to enable per-process tracking.
133 Print callchain information to file
139 this information is sent to the output file specified by the
142 .It Fl M Ar mapfilename
143 Write the mapping between executable objects encountered in the event
144 log and the abbreviated pathnames used for
148 If this option is not specified, mapping information is not written.
153 in which case this mapping information is sent to the output
154 file configured by the
158 Toggle capturing callchain information for subsequent sampling PMCs.
159 The default is for sampling PMCs to capture callchain information.
160 .It Fl O Ar logfilename
161 Send logging output to file
166 .Ar hostname Ns : Ns Ar port ,
169 does not start with a
175 will open a network socket to host
182 option is not specified and one of the logging options is requested,
185 will print a textual form of the logged events to the configured
187 .It Fl P Ar event-spec
188 Allocate a process mode sampling PMC measuring hardware events
191 .It Fl R Ar logfilename
192 Perform offline analysis using sampling data in file
194 .It Fl S Ar event-spec
195 Allocate a system mode sampling PMC measuring hardware events
199 Toggle logging the incremental counts seen by the threads of a
200 tracked process each time they are scheduled on a CPU.
201 This is an experimental feature intended to help analyse the
202 dynamic behaviour of processes in the system.
203 It may incur substantial overhead if enabled.
204 The default is for this feature to be disabled.
206 Set the cpus for subsequent system mode PMCs specified on the
211 is a comma separated list of CPU numbers, or the literal
213 denoting all unhalted CPUs.
214 The default is to allocate system mode PMCs on all unhalted
217 Toggle between process mode PMCs measuring events for the target
218 process' current and future children or only measuring events for
220 The default is to measure events for the target process alone.
222 Produce profiles in a format compatible with
224 A separate profile file is generated for each executable object
226 Profile files are placed in sub-directories named by their PMC
228 .It Fl k Ar kerneldir
229 Set the pathname of the kernel directory to argument
231 This directory specifies where
233 should look for the kernel and its modules.
237 Print the sampled PCs with the name, the start and ending addresses
238 of the function within they live.
241 argument is mandatory and indicates where informations will be stored.
246 this information is sent to the output file specified by the
250 Set the default sampling rate for subsequent sampling mode
251 PMCs specified on the command line.
252 The default is to configure PMCs to sample the CPU's instruction
253 pointer every 65536 events.
254 .It Fl o Ar outputfile
255 Send counter readings and textual representations of logged data
258 The default is to send output to
260 when collecting live data and to
262 when processing a pre-existing logfile.
263 .It Fl p Ar event-spec
264 Allocate a process mode counting PMC measuring hardware events
270 Set the top of the filesystem hierarchy under which executables
271 are located to argument
275 .It Fl s Ar event-spec
276 Allocate a system mode counting PMC measuring hardware events
279 .It Fl t Ar process-spec
280 Attach process mode PMCs to the processes named by argument
284 may be a non-negative integer denoting a specific process id, or a
285 regular expression for selecting processes based on their command names.
289 Print the values of all counting mode PMCs every
294 may be a fractional value.
295 The default interval is 5 seconds.
296 .It Fl z Ar graphdepth
297 When printing system-wide callgraphs, limit callgraphs to the depth
298 specified by argument
304 is specified, it is executed using
307 To perform system-wide statistical sampling on an AMD Athlon CPU with
308 samples taken every 32768 instruction retirals and data being sampled
312 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
316 and measure the number of data cache misses suffered
317 by it and its children every 12 seconds on an AMD Athlon, use:
318 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
320 To measure instructions retired for all processes named
323 .Dl "pmcstat -t '^emacs$' -p instructions"
325 To measure instructions retired for processes named
327 for a period of 10 seconds use:
328 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
330 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
331 Pentium Pro/Pentium III SMP system use:
332 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
334 To collect profiling information for a specific process with pid 1234
335 based on instruction cache misses seen by it use:
336 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
338 To perform system-wide sampling on all configured processors
339 based on processor instructions retired use:
340 .Dl "pmcstat -S instructions -O /tmp/sample.out"
341 If callgraph capture is not desired use:
342 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
344 To send the generated event log to a remote machine use:
345 .Dl "pmcstat -S instructions -O remotehost:port"
346 On the remote machine, the sample log can be collected using
348 .Dl "nc -l remotehost port > /tmp/sample.out"
352 compatible profiles from a sample file use:
353 .Dl "pmcstat -R /tmp/sample.out -g"
355 To print a system-wide profile with callgraphs to file
358 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
364 may issue the following diagnostic messages:
365 .Bl -diag -width indent
366 .It "#callchain/dubious-frames"
367 The number of callchain records that had an
369 value for a return address.
370 .It "#exec handling errors"
373 events in the log file that named executables that could not be
378 events that named ELF executables.
382 events that named executables with unrecognized formats.
384 The total number of samples in the log file.
385 .It "#samples/unclaimed"
386 The number of samples that could not be correlated to a known
387 executable object (i.e., to an executable, shared library, the
388 kernel or the runtime loader).
389 .It "#samples/unknown-object"
390 The number of samples that were associated with an executable
391 with an unrecognized object format.
396 Due to the limitations of the
400 compatible profiles generated by the
402 option do not contain information about calls that cross executable
406 files are also only meaningful for native executables.
419 utility first appeared in
424 .An Joseph Koshy Aq jkoshy@FreeBSD.org
428 utility cannot yet analyse
430 logs generated by non-native architectures.
projects / FreeBSD / releng / 8.0.git / blob