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