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
  14 DESCRIPTION
  15 -----------
  16 This command runs a command and gathers performance counter statistics
  17 from it.
  18
  19
  20 OPTIONS
  21 -------
  22 <command>...::
  23         Any command you can specify in a shell.
  24
  25
  26 -e::
  27 --event=::
  28         Select the PMU event. Selection can be a symbolic event name
  29         (use 'perf list' to list all events) or a raw PMU
  30         event (eventsel+umask) in the form of rNNN where NNN is a
  31          hexadecimal event descriptor.
  32
  33 -i::
  34 --no-inherit::
  35         child tasks do not inherit counters
  36 -p::
  37 --pid=<pid>::
  38         stat events on existing process id
  39
  40 -t::
  41 --tid=<tid>::
  42         stat events on existing thread id
  43
  44
  45 -a::
  46 --all-cpus::
  47         system-wide collection from all CPUs
  48
  49 -c::
  50 --scale::
  51         scale/normalize counter values
  52
  53 -r::
  54 --repeat=<n>::
  55         repeat command and print average + stddev (max: 100)
  56
  57 -B::
  58 --big-num::
  59         print large numbers with thousands' separators according to locale
  60
  61 -C::
  62 --cpu=::
  63 Count only on the list of CPUs provided. Multiple CPUs can be provided as a
  64 comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
  65 In per-thread mode, this option is ignored. The -a option is still necessary
  66 to activate system-wide monitoring. Default is to count on all CPUs.
  67
  68 -A::
  69 --no-aggr::
  70 Do not aggregate counts across all monitored CPUs in system-wide mode (-a).
  71 This option is only valid in system-wide mode.
  72
  73 -n::
  74 --null::
  75         null run - don't start any counters
  76
  77 -v::
  78 --verbose::
  79         be more verbose (show counter open errors, etc)
  80
  81 -x SEP::
  82 --field-separator SEP::
  83 print counts using a CSV-style output to make it easy to import directly into
  84 spreadsheets. Columns are separated by the string specified in SEP.
  85
  86 EXAMPLES
  87 --------
  88
  89 $ perf stat -- make -j
  90
  91  Performance counter stats for 'make -j':
  92
  93     8117.370256  task clock ticks     #      11.281 CPU utilization factor
  94             678  context switches     #       0.000 M/sec
  95             133  CPU migrations       #       0.000 M/sec
  96          235724  pagefaults           #       0.029 M/sec
  97     24821162526  CPU cycles           #    3057.784 M/sec
  98     18687303457  instructions         #    2302.138 M/sec
  99       172158895  cache references     #      21.209 M/sec
 100        27075259  cache misses         #       3.335 M/sec
 101
 102  Wall-clock time elapsed:   719.554352 msecs
 103
 104 SEE ALSO
 105 --------
 106 linkperf:perf-top[1], linkperf:perf-list[1]