perf-stat(1)
============

NAME
----
perf-stat - Run a command and gather performance counter statistics

SYNOPSIS
--------
[verse]
'perf stat' [-e <EVENT> | --event=EVENT] [-a] <command>
'perf stat' [-e <EVENT> | --event=EVENT] [-a] \-- <command> [<options>]
'perf stat' [-e <EVENT> | --event=EVENT] [-a] record [-o file] \-- <command> [<options>]
'perf stat' report [-i file]

DESCRIPTION
-----------
This command runs a command and gathers performance counter statistics
from it.


OPTIONS
-------
<command>...::
	Any command you can specify in a shell.

record::
	See STAT RECORD.

report::
	See STAT REPORT.

-e::
--event=::
	Select the PMU event. Selection can be:

	- a symbolic event name (use 'perf list' to list all events)

	- a raw PMU event in the form of rN where N is a hexadecimal value
	  that represents the raw register encoding with the layout of the
	  event control registers as described by entries in
	  /sys/bus/event_source/devices/cpu/format/*.

        - a symbolic or raw PMU event followed by an optional colon
	  and a list of event modifiers, e.g., cpu-cycles:p.  See the
	  linkperf:perf-list[1] man page for details on event modifiers.

	- a symbolically formed event like 'pmu/param1=0x3,param2/' where
	  param1 and param2 are defined as formats for the PMU in
	  /sys/bus/event_source/devices/<pmu>/format/*

	  'percore' is a event qualifier that sums up the event counts for both
	  hardware threads in a core. For example:
	  perf stat -A -a -e cpu/event,percore=1/,otherevent ...

	- a symbolically formed event like 'pmu/config=M,config1=N,config2=K/'
	  where M, N, K are numbers (in decimal, hex, octal format).
	  Acceptable values for each of 'config', 'config1' and 'config2'
	  parameters are defined by corresponding entries in
	  /sys/bus/event_source/devices/<pmu>/format/*

	Note that the last two syntaxes support prefix and glob matching in
	the PMU name to simplify creation of events across multiple instances
	of the same type of PMU in large systems (e.g. memory controller PMUs).
	Multiple PMU instances are typical for uncore PMUs, so the prefix
	'uncore_' is also ignored when performing this match.


-i::
--no-inherit::
        child tasks do not inherit counters
-p::
--pid=<pid>::
        stat events on existing process id (comma separated list)

-t::
--tid=<tid>::
        stat events on existing thread id (comma separated list)

-b::
--bpf-prog::
        stat events on existing bpf program id (comma separated list),
        requiring root rights. bpftool-prog could be used to find program
        id all bpf programs in the system. For example:

  # bpftool prog | head -n 1
  17247: tracepoint  name sys_enter  tag 192d548b9d754067  gpl

  # perf stat -e cycles,instructions --bpf-prog 17247 --timeout 1000

   Performance counter stats for 'BPF program(s) 17247':

             85,967      cycles
             28,982      instructions              #    0.34  insn per cycle

        1.102235068 seconds time elapsed

--bpf-counters::
	Use BPF programs to aggregate readings from perf_events.  This
	allows multiple perf-stat sessions that are counting the same metric (cycles,
	instructions, etc.) to share hardware counters.
	To use BPF programs on common events by default, use
	"perf config stat.bpf-counter-events=<list_of_events>".

--bpf-attr-map::
	With option "--bpf-counters", different perf-stat sessions share
	information about shared BPF programs and maps via a pinned hashmap.
	Use "--bpf-attr-map" to specify the path of this pinned hashmap.
	The default path is /sys/fs/bpf/perf_attr_map.

ifdef::HAVE_LIBPFM[]
--pfm-events events::
Select a PMU event using libpfm4 syntax (see http://perfmon2.sf.net)
including support for event filters. For example '--pfm-events
inst_retired:any_p:u:c=1:i'. More than one event can be passed to the
option using the comma separator. Hardware events and generic hardware
events cannot be mixed together. The latter must be used with the -e
option. The -e option and this one can be mixed and matched.  Events
can be grouped using the {} notation.
endif::HAVE_LIBPFM[]

-a::
--all-cpus::
        system-wide collection from all CPUs (default if no target is specified)

--no-scale::
	Don't scale/normalize counter values

-d::
--detailed::
	print more detailed statistics, can be specified up to 3 times

	   -d:          detailed events, L1 and LLC data cache
        -d -d:     more detailed events, dTLB and iTLB events
     -d -d -d:     very detailed events, adding prefetch events

-r::
--repeat=<n>::
	repeat command and print average + stddev (max: 100). 0 means forever.

-B::
--big-num::
        print large numbers with thousands' separators according to locale.
	Enabled by default. Use "--no-big-num" to disable.
	Default setting can be changed with "perf config stat.big-num=false".

-C::
--cpu=::
Count only on the list of CPUs provided. Multiple CPUs can be provided as a
comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
In per-thread mode, this option is ignored. The -a option is still necessary
to activate system-wide monitoring. Default is to count on all CPUs.

-A::
--no-aggr::
Do not aggregate counts across all monitored CPUs.

-n::
--null::
null run - Don't start any counters.

This can be useful to measure just elapsed wall-clock time - or to assess the
raw overhead of perf stat itself, without running any counters.

-v::
--verbose::
        be more verbose (show counter open errors, etc)

-x SEP::
--field-separator SEP::
print counts using a CSV-style output to make it easy to import directly into
spreadsheets. Columns are separated by the string specified in SEP.

--table:: Display time for each run (-r option), in a table format, e.g.:

  $ perf stat --null -r 5 --table perf bench sched pipe

   Performance counter stats for 'perf bench sched pipe' (5 runs):

             # Table of individual measurements:
             5.189 (-0.293) #
             5.189 (-0.294) #
             5.186 (-0.296) #
             5.663 (+0.181) ##
             6.186 (+0.703) ####

             # Final result:
             5.483 +- 0.198 seconds time elapsed  ( +-  3.62% )

-G name::
--cgroup name::
monitor only in the container (cgroup) called "name". This option is available only
in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to
container "name" are monitored when they run on the monitored CPUs. Multiple cgroups
can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup
to first event, second cgroup to second event and so on. It is possible to provide
an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have
corresponding events, i.e., they always refer to events defined earlier on the command
line. If the user wants to track multiple events for a specific cgroup, the user can
use '-e e1 -e e2 -G foo,foo' or just use '-e e1 -e e2 -G foo'.

If wanting to monitor, say, 'cycles' for a cgroup and also for system wide, this
command line can be used: 'perf stat -e cycles -G cgroup_name -a -e cycles'.

--for-each-cgroup name::
Expand event list for each cgroup in "name" (allow multiple cgroups s