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 'perf stat' report [-i file]
  15
  16 DESCRIPTION
  17 -----------
  18 This command runs a command and gathers performance counter statistics
  19 from it.
  20
  21
  22 OPTIONS
  23 -------
  24 <command>...::
  25         Any command you can specify in a shell.
  26
  27 record::
  28         See STAT RECORD.
  29
  30 report::
  31         See STAT REPORT.
  32
  33 -e::
  34 --event=::
  35         Select the PMU event. Selection can be:
  36
  37         - a symbolic event name (use 'perf list' to list all events)
  38
  39         - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a
  40           hexadecimal event descriptor.
  41
  42         - a symbolic or raw PMU event followed by an optional colon
  43           and a list of event modifiers, e.g., cpu-cycles:p.  See the
  44           linkperf:perf-list[1] man page for details on event modifiers.
  45
  46         - a symbolically formed event like 'pmu/param1=0x3,param2/' where
  47           param1 and param2 are defined as formats for the PMU in
  48           /sys/bus/event_sources/devices/<pmu>/format/*
  49
  50         - a symbolically formed event like 'pmu/config=M,config1=N,config2=K/'
  51           where M, N, K are numbers (in decimal, hex, octal format).
  52           Acceptable values for each of 'config', 'config1' and 'config2'
  53           parameters are defined by corresponding entries in
  54           /sys/bus/event_sources/devices/<pmu>/format/*
  55
  56 -i::
  57 --no-inherit::
  58         child tasks do not inherit counters
  59 -p::
  60 --pid=<pid>::
  61         stat events on existing process id (comma separated list)
  62
  63 -t::
  64 --tid=<tid>::
  65         stat events on existing thread id (comma separated list)
  66
  67
  68 -a::
  69 --all-cpus::
  70         system-wide collection from all CPUs
  71
  72 -c::
  73 --scale::
  74         scale/normalize counter values
  75
  76 -d::
  77 --detailed::
  78         print more detailed statistics, can be specified up to 3 times
  79
  80            -d:          detailed events, L1 and LLC data cache
  81         -d -d:     more detailed events, dTLB and iTLB events
  82      -d -d -d:     very detailed events, adding prefetch events
  83
  84 -r::
  85 --repeat=<n>::
  86         repeat command and print average + stddev (max: 100). 0 means forever.
  87
  88 -B::
  89 --big-num::
  90         print large numbers with thousands' separators according to locale
  91
  92 -C::
  93 --cpu=::
  94 Count only on the list of CPUs provided. Multiple CPUs can be provided as a
  95 comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
  96 In per-thread mode, this option is ignored. The -a option is still necessary
  97 to activate system-wide monitoring. Default is to count on all CPUs.
  98
  99 -A::
 100 --no-aggr::
 101 Do not aggregate counts across all monitored CPUs in system-wide mode (-a).
 102 This option is only valid in system-wide mode.
 103
 104 -n::
 105 --null::
 106         null run - don't start any counters
 107
 108 -v::
 109 --verbose::
 110         be more verbose (show counter open errors, etc)
 111
 112 -x SEP::
 113 --field-separator SEP::
 114 print counts using a CSV-style output to make it easy to import directly into
 115 spreadsheets. Columns are separated by the string specified in SEP.
 116
 117 -G name::
 118 --cgroup name::
 119 monitor only in the container (cgroup) called "name". This option is available only
 120 in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to
 121 container "name" are monitored when they run on the monitored CPUs. Multiple cgroups
 122 can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup
 123 to first event, second cgroup to second event and so on. It is possible to provide
 124 an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have
 125 corresponding events, i.e., they always refer to events defined earlier on the command
 126 line.
 127
 128 -o file::
 129 --output file::
 130 Print the output into the designated file.
 131
 132 --append::
 133 Append to the output file designated with the -o option. Ignored if -o is not specified.
 134
 135 --log-fd::
 136
 137 Log output to fd, instead of stderr.  Complementary to --output, and mutually exclusive
 138 with it.  --append may be used here.  Examples:
 139      3>results  perf stat --log-fd 3          -- $cmd
 140      3>>results perf stat --log-fd 3 --append -- $cmd
 141
 142 --pre::
 143 --post::
 144         Pre and post measurement hooks, e.g.:
 145
 146 perf stat --repeat 10 --null --sync --pre 'make -s O=defconfig-build/clean' -- make -s -j64 O=defconfig-build/ bzImage
 147
 148 -I msecs::
 149 --interval-print msecs::
 150 Print count deltas every N milliseconds (minimum: 10ms)
 151 The overhead percentage could be high in some cases, for instance with small, sub 100ms intervals.  Use with caution.
 152         example: 'perf stat -I 1000 -e cycles -a sleep 5'
 153
 154 --metric-only::
 155 Only print computed metrics. Print them in a single line.
 156 Don't show any raw values. Not supported with --per-thread.
 157
 158 --per-socket::
 159 Aggregate counts per processor socket for system-wide mode measurements.  This
 160 is a useful mode to detect imbalance between sockets.  To enable this mode,
 161 use --per-socket in addition to -a. (system-wide).  The output includes the
 162 socket number and the number of online processors on that socket. This is
 163 useful to gauge the amount of aggregation.
 164
 165 --per-core::
 166 Aggregate counts per physical processor for system-wide mode measurements.  This
 167 is a useful mode to detect imbalance between physical cores.  To enable this mode,
 168 use --per-core in addition to -a. (system-wide).  The output includes the
 169 core number and the number of online logical processors on that physical processor.
 170
 171 --per-thread::
 172 Aggregate counts per monitored threads, when monitoring threads (-t option)
 173 or processes (-p option).
 174
 175 -D msecs::
 176 --delay msecs::
 177 After starting the program, wait msecs before measuring. This is useful to
 178 filter out the startup phase of the program, which is often very different.
 179
 180 -T::
 181 --transaction::
 182
 183 Print statistics of transactional execution if supported.
 184
 185 STAT RECORD
 186 -----------
 187 Stores stat data into perf data file.
 188
 189 -o file::
 190 --output file::
 191 Output file name.
 192
 193 STAT REPORT
 194 -----------
 195 Reads and reports stat data from perf data file.
 196
 197 -i file::
 198 --input file::
 199 Input file name.
 200
 201 --per-socket::
 202 Aggregate counts per processor socket for system-wide mode measurements.
 203
 204 --per-core::
 205 Aggregate counts per physical processor for system-wide mode measurements.
 206
 207 -A::
 208 --no-aggr::
 209 Do not aggregate counts across all monitored CPUs.
 210
 211 --topdown::
 212 Print top down level 1 metrics if supported by the CPU. This allows to
 213 determine bottle necks in the CPU pipeline for CPU bound workloads,
 214 by breaking the cycles consumed down into frontend bound, backend bound,
 215 bad speculation and retiring.
 216
 217 Frontend bound means that the CPU cannot fetch and decode instructions fast
 218 enough. Backend bound means that computation or memory access is the bottle
 219 neck. Bad Speculation means that the CPU wasted cycles due to branch
 220 mispredictions and similar issues. Retiring means that the CPU computed without
 221 an apparently bottleneck. The bottleneck is only the real bottleneck
 222 if the workload is actually bound by the CPU and not by something else.
 223
 224 For best results it is usually a good idea to use it with interval
 225 mode like -I 1000, as the bottleneck of workloads can change often.
 226
 227 The top down metrics are collected per core instead of per
 228 CPU thread. Per core mode is automatically enabled
 229 and -a (global monitoring) is needed, requiring root rights or
 230 perf.perf_event_paranoid=-1.
 231
 232 Topdown uses the full Performance Monitoring Unit, and needs
 233 disabling of the NMI watchdog (as root):
 234 echo 0 > /proc/sys/kernel/nmi_watchdog
 235 for best results. Otherwise the bottlenecks may be inconsistent
 236 on workload with changing phases.
 237
 238 This enables --metric-only, unless overriden with --no-metric-only.
 239
 240 To interpret the results it is usually needed to know on which
 241 CPUs the workload runs on. If needed the CPUs can be forced using
 242 taskset.
 243
 244 EXAMPLES
 245 --------
 246
 247 $ perf stat -- make -j
 248
 249  Performance counter stats for 'make -j':
 250
 251     8117.370256  task clock ticks     #      11.281 CPU utilization factor
 252             678  context switches     #       0.000 M/sec
 253             133  CPU migrations       #       0.000 M/sec
 254          235724  pagefaults           #       0.029 M/sec
 255     24821162526  CPU cycles           #    3057.784 M/sec
 256     18687303457  instructions         #    2302.138 M/sec
 257       172158895  cache references     #      21.209 M/sec
 258        27075259  cache misses         #       3.335 M/sec
 259
 260  Wall-clock time elapsed:   719.554352 msecs
 261
 262 CSV FORMAT
 263 ----------
 264
 265 With -x, perf stat is able to output a not-quite-CSV format output
 266 Commas in the output are not put into "". To make it easy to parse
 267 it is recommended to use a different character like -x \;
 268
 269 The fields are in this order:
 270
 271         - optional usec time stamp in fractions of second (with -I xxx)
 272         - optional CPU, core, or socket identifier
 273         - optional number of logical CPUs aggregated
 274         - counter value
 275         - unit of the counter value or empty
 276         - event name
 277         - run time of counter
 278         - percentage of measurement time the counter was running
 279         - optional variance if multiple values are collected with -r
 280         - optional metric value
 281         - optional unit of metric
 282
 283 Additional metrics may be printed with all earlier fields being empty.
 284
 285 SEE ALSO
 286 --------
 287 linkperf:perf-top[1], linkperf:perf-list[1]