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