usr.sbin/pmcstat/pmcstat.8

   1 .\" Copyright (c) 2003-2008 Joseph Koshy
   2 .\" Copyright (c) 2007 The FreeBSD Foundation
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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
  24 .\" such damage.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 19, 2008
  29 .Dt PMCSTAT 8
  30 .Os
  31 .Sh NAME
  32 .Nm pmcstat
  33 .Nd "performance measurement with performance monitoring hardware"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl C
  37 .Op Fl D Ar pathname
  38 .Op Fl E
  39 .Op Fl F Ar pathname
  40 .Op Fl G Ar pathname
  41 .Op Fl M Ar mapfilename
  42 .Op Fl N
  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
  47 .Op Fl T
  48 .Op Fl W
  49 .Op Fl c Ar cpu-spec
  50 .Op Fl d
  51 .Op Fl f Ar pluginopt
  52 .Op Fl g
  53 .Op Fl k Ar kerneldir
  54 .Op Fl m Ar pathname
  55 .Op Fl n Ar rate
  56 .Op Fl o Ar outputfile
  57 .Op Fl p Ar event-spec
  58 .Op Fl q
  59 .Op Fl r Ar fsroot
  60 .Op Fl s Ar event-spec
  61 .Op Fl t Ar process-spec
  62 .Op Fl v
  63 .Op Fl w Ar secs
  64 .Op Fl z Ar graphdepth
  65 .Op Ar command Op Ar args
  66 .Sh DESCRIPTION
  67 The
  68 .Nm
  69 utility measures system performance using the facilities provided by
  70 .Xr hwpmc 4 .
  71 .Pp
  72 The
  73 .Nm
  74 utility can measure both hardware events seen by the system as a
  75 whole, and those seen when a specified set of processes are executing
  76 on the system's CPUs.
  77 If a specific set of processes is being targeted (for example,
  78 if the
  79 .Fl t Ar process-spec
  80 option is specified, or if a command line is specified using
  81 .Ar command ) ,
  82 then measurement occurs till
  83 .Ar command
  84 exits, or till all target processes specified by the
  85 .Fl t Ar process-spec
  86 options exit, or till the
  87 .Nm
  88 utility is interrupted by the user.
  89 If a specific set of processes is not targeted for measurement, then
  90 .Nm
  91 will perform system-wide measurements till interrupted by the
  92 user.
  93 .Pp
  94 A given invocation of
  95 .Nm
  96 can mix allocations of system-mode and process-mode PMCs, of both
  97 counting and sampling flavors.
  98 The values of all counting PMCs are printed in human readable form
  99 at regular intervals by
 100 .Nm .
 101 The output of sampling PMCs may be configured to go to a log file for
 102 subsequent offline analysis, or, at the expense of greater
 103 overhead, may be configured to be printed in text form on the fly.
 104 .Pp
 105 Hardware events to measure are specified to
 106 .Nm
 107 using event specifier strings
 108 .Ar event-spec .
 109 The syntax of these event specifiers is machine dependent and is
 110 documented in
 111 .Xr pmc 3 .
 112 .Pp
 113 A process-mode PMC may be configured to be inheritable by the target
 114 process' current and future children.
 115 .Sh OPTIONS
 116 The following options are available:
 117 .Bl -tag -width indent
 118 .It Fl C
 119 Toggle between showing cumulative or incremental counts for
 120 subsequent counting mode PMCs specified on the command line.
 121 The default is to show incremental counts.
 122 .It Fl D Ar pathname
 123 Create files with per-program samples in the directory named
 124 by
 125 .Ar pathname .
 126 The default is to create these files in the current directory.
 127 .It Fl E
 128 Toggle showing per-process counts at the time a tracked process
 129 exits for subsequent process-mode PMCs specified on the command line.
 130 This option is useful for mapping the performance characteristics of a
 131 complex pipeline of processes when used in conjunction with the
 132 .Fl d
 133 option.
 134 The default is to not to enable per-process tracking.
 135 .It Fl F Ar pathname
 136 Print calltree (Kcachegrind) information to file
 137 .Ar pathname .
 138 If argument
 139 .Ar pathname
 140 is a
 141 .Dq Li -
 142 this information is sent to the output file specified by the
 143 .Fl o
 144 option.
 145 .It Fl G Ar pathname
 146 Print callchain information to file
 147 .Ar pathname .
 148 If argument
 149 .Ar pathname
 150 is a
 151 .Dq Li -
 152 this information is sent to the output file specified by the
 153 .Fl o
 154 option.
 155 .It Fl M Ar mapfilename
 156 Write the mapping between executable objects encountered in the event
 157 log and the abbreviated pathnames used for
 158 .Xr gprof 1
 159 profiles to file
 160 .Ar mapfilename .
 161 If this option is not specified, mapping information is not written.
 162 Argument
 163 .Ar mapfilename
 164 may be a
 165 .Dq Li -
 166 in which case this mapping information is sent to the output
 167 file configured by the
 168 .Fl o
 169 option.
 170 .It Fl N
 171 Toggle capturing callchain information for subsequent sampling PMCs.
 172 The default is for sampling PMCs to capture callchain information.
 173 .It Fl O Ar logfilename
 174 Send logging output to file
 175 .Ar logfilename .
 176 If
 177 .Ar logfilename
 178 is of the form
 179 .Ar hostname Ns : Ns Ar port ,
 180 where
 181 .Ar hostname
 182 does not start with a
 183 .Ql \&.
 184 or a
 185 .Ql / ,
 186 then
 187 .Nm
 188 will open a network socket to host
 189 .Ar hostname
 190 on port
 191 .Ar port .
 192 .Pp
 193 If the
 194 .Fl O
 195 option is not specified and one of the logging options is requested,
 196 then
 197 .Nm
 198 will print a textual form of the logged events to the configured
 199 output file.
 200 .It Fl P Ar event-spec
 201 Allocate a process mode sampling PMC measuring hardware events
 202 specified in
 203 .Ar event-spec .
 204 .It Fl R Ar logfilename
 205 Perform offline analysis using sampling data in file
 206 .Ar logfilename .
 207 .It Fl S Ar event-spec
 208 Allocate a system mode sampling PMC measuring hardware events
 209 specified in
 210 .Ar event-spec .
 211 .It Fl T
 212 Use a top like mode for sampling PMCs. The following hotkeys
 213 can be used: 'c+a' switch to accumulative mode, 'c+d' switch
 214 to delta mode, 'm' merge PMCs, 'n' change view, 'p' show next
 215 PMC, ' ' pause, 'q' quit. calltree only: 'f' cost under threshold
 216 is seen as a dot.
 217 .It Fl W
 218 Toggle logging the incremental counts seen by the threads of a
 219 tracked process each time they are scheduled on a CPU.
 220 This is an experimental feature intended to help analyse the
 221 dynamic behaviour of processes in the system.
 222 It may incur substantial overhead if enabled.
 223 The default is for this feature to be disabled.
 224 .It Fl c Ar cpu-spec
 225 Set the cpus for subsequent system mode PMCs specified on the
 226 command line to
 227 .Ar cpu-spec .
 228 Argument
 229 .Ar cpu-spec
 230 is a comma separated list of CPU numbers, or the literal
 231 .Sq *
 232 denoting all unhalted CPUs.
 233 The default is to allocate system mode PMCs on all unhalted
 234 CPUs.
 235 .It Fl d
 236 Toggle between process mode PMCs measuring events for the target
 237 process' current and future children or only measuring events for
 238 the target process.
 239 The default is to measure events for the target process alone.
 240 .It Fl f Ar pluginopt
 241 Pass option string to the active plugin.
 242 .br
 243 threshold=<float> do not display cost under specified value (Top).
 244 .br
 245 skiplink=0|1 replace node with cost under threshold by a dot (Top).
 246 .It Fl g
 247 Produce profiles in a format compatible with
 248 .Xr gprof 1 .
 249 A separate profile file is generated for each executable object
 250 encountered.
 251 Profile files are placed in sub-directories named by their PMC
 252 event name.
 253 .It Fl k Ar kerneldir
 254 Set the pathname of the kernel directory to argument
 255 .Ar kerneldir .
 256 This directory specifies where
 257 .Nm
 258 should look for the kernel and its modules.
 259 The default is
 260 .Pa /boot/kernel .
 261 .It Fl m Ar pathname
 262 Print the sampled PCs with the name, the start and ending addresses
 263 of the function within they live.
 264 The
 265 .Ar pathname
 266 argument is mandatory and indicates where the information will be stored.
 267 If argument
 268 .Ar pathname
 269 is a
 270 .Dq Li -
 271 this information is sent to the output file specified by the
 272 .Fl o
 273 option.
 274 .It Fl n Ar rate
 275 Set the default sampling rate for subsequent sampling mode
 276 PMCs specified on the command line.
 277 The default is to configure PMCs to sample the CPU's instruction
 278 pointer every 65536 events.
 279 .It Fl o Ar outputfile
 280 Send counter readings and textual representations of logged data
 281 to file
 282 .Ar outputfile .
 283 The default is to send output to
 284 .Pa stderr
 285 when collecting live data and to
 286 .Pa stdout
 287 when processing a pre-existing logfile.
 288 .It Fl p Ar event-spec
 289 Allocate a process mode counting PMC measuring hardware events
 290 specified in
 291 .Ar event-spec .
 292 .It Fl q
 293 Decrease verbosity.
 294 .It Fl r Ar fsroot
 295 Set the top of the filesystem hierarchy under which executables
 296 are located to argument
 297 .Ar fsroot .
 298 The default is
 299 .Pa / .
 300 .It Fl s Ar event-spec
 301 Allocate a system mode counting PMC measuring hardware events
 302 specified in
 303 .Ar event-spec .
 304 .It Fl t Ar process-spec
 305 Attach process mode PMCs to the processes named by argument
 306 .Ar process-spec .
 307 Argument
 308 .Ar process-spec
 309 may be a non-negative integer denoting a specific process id, or a
 310 regular expression for selecting processes based on their command names.
 311 .It Fl v
 312 Increase verbosity.
 313 .It Fl w Ar secs
 314 Print the values of all counting mode PMCs or sampling mode PMCs
 315 for top mode every
 316 .Ar secs
 317 seconds.
 318 The argument
 319 .Ar secs
 320 may be a fractional value.
 321 The default interval is 5 seconds.
 322 .It Fl z Ar graphdepth
 323 When printing system-wide callgraphs, limit callgraphs to the depth
 324 specified by argument
 325 .Ar graphdepth .
 326 .El
 327 .Pp
 328 If
 329 .Ar command
 330 is specified, it is executed using
 331 .Xr execvp 3 .
 332 .Sh EXAMPLES
 333 To perform system-wide statistical sampling on an AMD Athlon CPU with
 334 samples taken every 32768 instruction retirals and data being sampled
 335 to file
 336 .Pa sample.stat ,
 337 use:
 338 .Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
 339 .Pp
 340 To execute
 341 .Nm firefox
 342 and measure the number of data cache misses suffered
 343 by it and its children every 12 seconds on an AMD Athlon, use:
 344 .Dl "pmcstat -d -w 12 -p k7-dc-misses firefox"
 345 .Pp
 346 To measure instructions retired for all processes named
 347 .Dq emacs
 348 use:
 349 .Dl "pmcstat -t '^emacs$' -p instructions"
 350 .Pp
 351 To measure instructions retired for processes named
 352 .Dq emacs
 353 for a period of 10 seconds use:
 354 .Dl "pmcstat -t '^emacs$' -p instructions sleep 10"
 355 .Pp
 356 To count instruction tlb-misses on CPUs 0 and 2 on a Intel
 357 Pentium Pro/Pentium III SMP system use:
 358 .Dl "pmcstat -c 0,2 -s p6-itlb-miss"
 359 .Pp
 360 To collect profiling information for a specific process with pid 1234
 361 based on instruction cache misses seen by it use:
 362 .Dl "pmcstat -P ic-misses -t 1234 -O /tmp/sample.out"
 363 .Pp
 364 To perform system-wide sampling on all configured processors
 365 based on processor instructions retired use:
 366 .Dl "pmcstat -S instructions -O /tmp/sample.out"
 367 If callgraph capture is not desired use:
 368 .Dl "pmcstat -N -S instructions -O /tmp/sample.out"
 369 .Pp
 370 To send the generated event log to a remote machine use:
 371 .Dl "pmcstat -S instructions -O remotehost:port"
 372 On the remote machine, the sample log can be collected using
 373 .Xr nc 1 :
 374 .Dl "nc -l remotehost port > /tmp/sample.out"
 375 .Pp
 376 To generate
 377 .Xr gprof 1
 378 compatible profiles from a sample file use:
 379 .Dl "pmcstat -R /tmp/sample.out -g"
 380 .Pp
 381 To print a system-wide profile with callgraphs to file
 382 .Pa "foo.graph"
 383 use:
 384 .Dl "pmcstat -R /tmp/sample.out -G foo.graph"
 385 .Sh DIAGNOSTICS
 386 If option
 387 .Fl v
 388 is specified,
 389 .Nm
 390 may issue the following diagnostic messages:
 391 .Bl -diag
 392 .It "#callchain/dubious-frames"
 393 The number of callchain records that had an
 394 .Dq impossible
 395 value for a return address.
 396 .It "#exec handling errors"
 397 The number of
 398 .Xr exec 2
 399 events in the log file that named executables that could not be
 400 analyzed.
 401 .It "#exec/elf"
 402 The number of
 403 .Xr exec 2
 404 events that named ELF executables.
 405 .It "#exec/unknown"
 406 The number of
 407 .Xr exec 2
 408 events that named executables with unrecognized formats.
 409 .It "#samples/total"
 410 The total number of samples in the log file.
 411 .It "#samples/unclaimed"
 412 The number of samples that could not be correlated to a known
 413 executable object (i.e., to an executable, shared library, the
 414 kernel or the runtime loader).
 415 .It "#samples/unknown-object"
 416 The number of samples that were associated with an executable
 417 with an unrecognized object format.
 418 .El
 419 .Pp
 420 .Ex -std
 421 .Sh COMPATIBILITY
 422 Due to the limitations of the
 423 .Pa gmon.out
 424 file format,
 425 .Xr gprof 1
 426 compatible profiles generated by the
 427 .Fl g
 428 option do not contain information about calls that cross executable
 429 boundaries.
 430 The generated
 431 .Pa gmon.out
 432 files are also only meaningful for native executables.
 433 .Sh SEE ALSO
 434 .Xr gprof 1 ,
 435 .Xr nc 1 ,
 436 .Xr execvp 3 ,
 437 .Xr pmc 3 ,
 438 .Xr pmclog 3 ,
 439 .Xr hwpmc 4 ,
 440 .Xr pmccontrol 8 ,
 441 .Xr sysctl 8
 442 .Sh HISTORY
 443 The
 444 .Nm
 445 utility first appeared in
 446 .Fx 6.0 .
 447 It is
 448 .Ud
 449 .Sh AUTHORS
 450 .An Joseph Koshy Aq jkoshy@FreeBSD.org
 451 .Sh BUGS
 452 The
 453 .Nm
 454 utility cannot yet analyse
 455 .Xr hwpmc 4
 456 logs generated by non-native architectures.