tools/perf/Documentation/perf-stat.txt

   1 perf-stat(1)
   2 ============
   3
   4 NAME
   5 ----
   6 perf-stat - Run a command and gather performance counter statistics
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'perf stat' [-e <EVENT> | --event=EVENT] [-a] <command>
  12 'perf stat' [-e <EVENT> | --event=EVENT] [-a] -- <command> [<options>]
  13 'perf stat' [-e <EVENT> | --event=EVENT] [-a] record [-o file] -- <command> [<options>]
  14
  15 DESCRIPTION
  16 -----------
  17 This command runs a command and gathers performance counter statistics
  18 from it.
  19
  20
  21 OPTIONS
  22 -------
  23 <command>...::
  24         Any command you can specify in a shell.
  25
  26 record::
  27         See STAT RECORD.
  28
  29 -e::
  30 --event=::
  31         Select the PMU event. Selection can be:
  32
  33         - a symbolic event name (use 'perf list' to list all events)
  34
  35         - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a
  36           hexadecimal event descriptor.
  37
  38         - a symbolically formed event like 'pmu/param1=0x3,param2/' where
  39           param1 and param2 are defined as formats for the PMU in
  40           /sys/bus/event_sources/devices/<pmu>/format/*
  41
  42         - a symbolically formed event like 'pmu/config=M,config1=N,config2=K/'
  43           where M, N, K are numbers (in decimal, hex, octal format).
  44           Acceptable values for each of 'config', 'config1' and 'config2'
  45           parameters are defined by corresponding entries in
  46           /sys/bus/event_sources/devices/<pmu>/format/*
  47
  48 -i::
  49 --no-inherit::
  50         child tasks do not inherit counters
  51 -p::
  52 --pid=<pid>::
  53         stat events on existing process id (comma separated list)
  54
  55 -t::
  56 --tid=<tid>::
  57         stat events on existing thread id (comma separated list)
  58
  59
  60 -a::
  61 --all-cpus::
  62         system-wide collection from all CPUs
  63
  64 -c::
  65 --scale::
  66         scale/normalize counter values
  67
  68 -r::
  69 --repeat=<n>::
  70         repeat command and print average + stddev (max: 100). 0 means forever.
  71
  72 -B::
  73 --big-num::
  74         print large numbers with thousands' separators according to locale
  75
  76 -C::
  77 --cpu=::
  78 Count only on the list of CPUs provided. Multiple CPUs can be provided as a
  79 comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
  80 In per-thread mode, this option is ignored. The -a option is still necessary
  81 to activate system-wide monitoring. Default is to count on all CPUs.
  82
  83 -A::
  84 --no-aggr::
  85 Do not aggregate counts across all monitored CPUs in system-wide mode (-a).
  86 This option is only valid in system-wide mode.
  87
  88 -n::
  89 --null::
  90         null run - don't start any counters
  91
  92 -v::
  93 --verbose::
  94         be more verbose (show counter open errors, etc)
  95
  96 -x SEP::
  97 --field-separator SEP::
  98 print counts using a CSV-style output to make it easy to import directly into
  99 spreadsheets. Columns are separated by the string specified in SEP.
 100
 101 -G name::
 102 --cgroup name::
 103 monitor only in the container (cgroup) called "name". This option is available only
 104 in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to
 105 container "name" are monitored when they run on the monitored CPUs. Multiple cgroups
 106 can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup
 107 to first event, second cgroup to second event and so on. It is possible to provide
 108 an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have
 109 corresponding events, i.e., they always refer to events defined earlier on the command
 110 line.
 111
 112 -o file::
 113 --output file::
 114 Print the output into the designated file.
 115
 116 --append::
 117 Append to the output file designated with the -o option. Ignored if -o is not specified.
 118
 119 --log-fd::
 120
 121 Log output to fd, instead of stderr.  Complementary to --output, and mutually exclusive
 122 with it.  --append may be used here.  Examples:
 123      3>results  perf stat --log-fd 3          -- $cmd
 124      3>>results perf stat --log-fd 3 --append -- $cmd
 125
 126 --pre::
 127 --post::
 128         Pre and post measurement hooks, e.g.:
 129
 130 perf stat --repeat 10 --null --sync --pre 'make -s O=defconfig-build/clean' -- make -s -j64 O=defconfig-build/ bzImage
 131
 132 -I msecs::
 133 --interval-print msecs::
 134 Print count deltas every N milliseconds (minimum: 10ms)
 135 The overhead percentage could be high in some cases, for instance with small, sub 100ms intervals.  Use with caution.
 136         example: 'perf stat -I 1000 -e cycles -a sleep 5'
 137
 138 --per-socket::
 139 Aggregate counts per processor socket for system-wide mode measurements.  This
 140 is a useful mode to detect imbalance between sockets.  To enable this mode,
 141 use --per-socket in addition to -a. (system-wide).  The output includes the
 142 socket number and the number of online processors on that socket. This is
 143 useful to gauge the amount of aggregation.
 144
 145 --per-core::
 146 Aggregate counts per physical processor for system-wide mode measurements.  This
 147 is a useful mode to detect imbalance between physical cores.  To enable this mode,
 148 use --per-core in addition to -a. (system-wide).  The output includes the
 149 core number and the number of online logical processors on that physical processor.
 150
 151 --per-thread::
 152 Aggregate counts per monitored threads, when monitoring threads (-t option)
 153 or processes (-p option).
 154
 155 -D msecs::
 156 --delay msecs::
 157 After starting the program, wait msecs before measuring. This is useful to
 158 filter out the startup phase of the program, which is often very different.
 159
 160 -T::
 161 --transaction::
 162
 163 Print statistics of transactional execution if supported.
 164
 165 STAT RECORD
 166 -----------
 167 Stores stat data into perf data file.
 168
 169 -o file::
 170 --output file::
 171 Output file name.
 172
 173
 174 EXAMPLES
 175 --------
 176
 177 $ perf stat -- make -j
 178
 179  Performance counter stats for 'make -j':
 180
 181     8117.370256  task clock ticks     #      11.281 CPU utilization factor
 182             678  context switches     #       0.000 M/sec
 183             133  CPU migrations       #       0.000 M/sec
 184          235724  pagefaults           #       0.029 M/sec
 185     24821162526  CPU cycles           #    3057.784 M/sec
 186     18687303457  instructions         #    2302.138 M/sec
 187       172158895  cache references     #      21.209 M/sec
 188        27075259  cache misses         #       3.335 M/sec
 189
 190  Wall-clock time elapsed:   719.554352 msecs
 191
 192 SEE ALSO
 193 --------
 194 linkperf:perf-top[1], linkperf:perf-list[1]