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