FreeBSD 7.0 manual page repository

FreeBSD is a free computer operating system based on BSD UNIX originally. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

pmcstat - performance measurement with performance monitoring hardware

 

NAME

      pmcstat - performance measurement with performance monitoring hardware
 

SYNOPSIS

      pmcstat [-C] [-D pathname] [-E] [-M mapfilename] [-O logfilename]
              [-P event-spec] [-R logfilename] [-S event-spec] [-W]
              [-c cpu-spec] [-d] [-g] [-k kerneldir] [-n rate] [-o outputfile]
              [-p event-spec] [-q] [-r fsroot] [-s event-spec]
              [-t process-spec] [-v] [-w secs] [command [args]]
 

DESCRIPTION

      The pmcstat utility measures system performance using the facilities pro‐
      vided by hwpmc(4).
 
      The pmcstat utility can measure both hardware events seen by the system
      as a whole, and those seen when a specified set of processes are execut‐
      ing on the system’s CPUs.  If a specific set of processes is being tar‐
      geted (for example, if the -t process-spec option is specified, or if a
      command line is specified using command), then measurement occurs till
      command exits, or till all target processes specified by the -t
      process-spec options exit, or till the pmcstat utility is interrupted by
      the user.  If a specific set of processes is not targeted for measure‐
      ment, then pmcstat will perform system-wide measurements till interrupted
      by the user.
 
      A given invocation of pmcstat can mix allocations of system-mode and pro‐
      cess-mode PMCs, of both counting and sampling flavors.  The values of all
      counting PMCs are printed in human readable form at regular intervals by
      pmcstat.  The output of sampling PMCs may be configured to go to a log
      file for subsequent offline analysis, or, at the expense of greater over‐
      head, may be configured to be printed in text form on the fly.
 
      Hardware events to measure are specified to pmcstat using event specifier
      strings event-spec.  The syntax of these event specifiers is machine
      dependent and is documented in pmc(3).
 
      A process-mode PMC may be configured to be inheritable by the target pro‐
      cess’ current and future children.
 

OPTIONS

      The following options are available:
 
      -C      Toggle between showing cumulative or incremental counts for sub‐
              sequent counting mode PMCs specified on the command line.  The
              default is to show incremental counts.
 
      -D pathname
              Create files with per-program samples in the directory named by
              pathname.  The default is to create these files in the current
              directory.
 
      -E      Toggle showing per-process counts at the time a tracked process
              exits for subsequent process-mode PMCs specified on the command
              line.  This option is useful for mapping the performance charac‐
              teristics of a complex pipeline of processes when used in con‐
              junction with the -d option.  The default is to not to enable
              per-process tracking.
 
      -M mapfilename
              Write the mapping between executable objects encountered in the
              event log and the abbreviated pathnames used for gprof(1) pro‐
              files to file mapfilename.  If this option is not specified, map‐
              ping information is not written.  Argument mapfilename may be a
              “-” in which case this mapping information is sent to the output
              file configured by the -o option.
 
      -O logfilename
              Send logging output to file logfilename.  If logfilename is of
              the form hostname:port, where hostname does not start with a ‘.’
              or a ‘/’, then pmcstat will open a network socket to host
              hostname on port port.
 
              If the -O option is not specified and one of the logging options
              is requested, then pmcstat will print a textual form of the
              logged events to the configured output file.
 
      -P event-spec
              Allocate a process mode sampling PMC measuring hardware events
              specified in event-spec.
 
      -R logfilename
              Perform offline analysis using sampling data in file logfilename.
 
      -S event-spec
              Allocate a system mode sampling PMC measuring hardware events
              specified in event-spec.
 
      -W      Toggle logging the incremental counts seen by the threads of a
              tracked process each time they are scheduled on a CPU.  This is
              an experimental feature intended to help analyse the dynamic
              behaviour of processes in the system.  It may incur substantial
              overhead if enabled.  The default is for this feature to be dis‐
              abled.
 
      -c cpu-spec
              Set the cpus for subsequent system mode PMCs specified on the
              command line to cpu-spec.  Argument cpu-spec is a comma separated
              list of CPU numbers, or the literal ‘*’ denoting all CPUs.  The
              default is to allocate system mode PMCs on all CPUs.
 
      -d      Toggle between process mode PMCs measuring events for the target
              process’ current and future children or only measuring events for
              the target process.  The default is to measure events for the
              target process alone.
 
      -g      Produce flat execution profiles in a format compatible with
              gprof(1).  A separate profile file is generated for each exe‐
              cutable object encountered.  Profile files are placed in sub-
              directories named by their PMC event name.
 
      -k kerneldir
              Set the pathname of the kernel directory to argument kerneldir.
              This directory specifies where pmcstat should look for the kernel
              and its modules.  The default is /boot/kernel.
 
      -n rate
              Set the default sampling rate for subsequent sampling mode PMCs
              specified on the command line.  The default is to configure PMCs
              to sample the CPU’s instruction pointer every 65536 events.
 
      -o outputfile
              Send counter readings and textual representations of logged data
              to file outputfile.  The default is to send output to stderr.
 
      -p event-spec
              Allocate a process mode counting PMC measuring hardware events
              specified in event-spec.
 
      -q      Decrease verbosity.
 
      -r fsroot
              Set the top of the filesystem hierarchy under which executables
              are located to argument fsroot.  The default is /.
 
      -s event-spec
              Allocate a system mode counting PMC measuring hardware events
              specified in event-spec.
 
      -t process-spec
              Attach process mode PMCs to the processes named by argument
              process-spec.  Argument process-spec may be a non-negative inte‐
              ger denoting a specific process id, or a regular expression for
              selecting processes based on their command names.
 
      -v      Increase verbosity.
 
      -w secs
              Print the values of all counting mode PMCs every secs seconds.
              The argument secs may be a fractional value.  The default inter‐
              val is 5 seconds.
 
      If command is specified, it is executed using execvp(3).
 

EXAMPLES

      To perform system-wide statistical sampling on an AMD Athlon CPU with
      samples taken every 32768 instruction retirals and data being sampled to
      file sample.stat, use:
            pmcstat -O sample.stat -n 32768 -S k7-retired-instructions
 
      To execute mozilla and measure the number of data cache misses suffered
      by it and its children every 12 seconds on an AMD Athlon, use:
            pmcstat -d -w 12 -p k7-dc-misses mozilla
 
      To measure processor instructions retired for all processes named “emacs”
      use:
            pmcstat -t ’^emacs$’ -p instructions
 
      To count instruction tlb-misses on CPUs 0 and 2 on a Intel Pentium
      Pro/Pentium III SMP system use:
            pmcstat -c 0,2 -s p6-itlb-miss
 
      To perform system-wide sampling on all configured processors based on
      processor instructions retired use:
            pmcstat -S instructions -O /tmp/sample.out
 
      To send the generated event log to a remote machine use:
            pmcstat -S instructions -O remotehost:port
      On the remote machine, the sample log can be collected using nc(1):
            nc -l remotehost port > /tmp/sample.out
 
      To generate gprof(1) compatible flat profiles from a sample file use:
            pmcstat -R /tmp/sample.out -g
 

DIAGNOSTICS

      The pmcstat utility exits 0 on success, and >0 if an error occurs.
      gprof(1), nc(1), execvp(3), pmc(3), pmclog(3), hwpmc(4), pmccontrol(8),
      sysctl(8)
 

HISTORY

      The pmcstat utility first appeared in FreeBSD 6.0.  It is currently under
      development.
 

AUTHORS

      Joseph Koshy 〈jkoshy@FreeBSD.org〉
 

BUGS

      The pmcstat utility cannot yet analyse hwpmc(4) logs generated by non-
      native architectures.
 

Sections

Based on BSD UNIX
FreeBSD is an advanced operating system for x86 compatible (including Pentium and Athlon), amd64 compatible (including Opteron, Athlon64, and EM64T), UltraSPARC, IA-64, PC-98 and ARM architectures. It is derived from BSD, the version of UNIX developed at the University of California, Berkeley. It is developed and maintained by a large team of individuals. Additional platforms are in various stages of development.