388 lines
13 KiB
Plaintext
388 lines
13 KiB
Plaintext
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 (eventsel+umask) in the form of rNNN where NNN is a
|
|
hexadecimal event descriptor.
|
|
|
|
- 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)
|
|
|
|
|
|
-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
|
|
|
|
-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
|
|
|
|
-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'.
|
|
|
|
-o file::
|
|
--output file::
|
|
Print the output into the designated file.
|
|
|
|
--append::
|
|
Append to the output file designated with the -o option. Ignored if -o is not specified.
|
|
|
|
--log-fd::
|
|
|
|
Log output to fd, instead of stderr. Complementary to --output, and mutually exclusive
|
|
with it. --append may be used here. Examples:
|
|
3>results perf stat --log-fd 3 -- $cmd
|
|
3>>results perf stat --log-fd 3 --append -- $cmd
|
|
|
|
--pre::
|
|
--post::
|
|
Pre and post measurement hooks, e.g.:
|
|
|
|
perf stat --repeat 10 --null --sync --pre 'make -s O=defconfig-build/clean' -- make -s -j64 O=defconfig-build/ bzImage
|
|
|
|
-I msecs::
|
|
--interval-print msecs::
|
|
Print count deltas every N milliseconds (minimum: 1ms)
|
|
The overhead percentage could be high in some cases, for instance with small, sub 100ms intervals. Use with caution.
|
|
example: 'perf stat -I 1000 -e cycles -a sleep 5'
|
|
|
|
--interval-count times::
|
|
Print count deltas for fixed number of times.
|
|
This option should be used together with "-I" option.
|
|
example: 'perf stat -I 1000 --interval-count 2 -e cycles -a'
|
|
|
|
--interval-clear::
|
|
Clear the screen before next interval.
|
|
|
|
--timeout msecs::
|
|
Stop the 'perf stat' session and print count deltas after N milliseconds (minimum: 10 ms).
|
|
This option is not supported with the "-I" option.
|
|
example: 'perf stat --time 2000 -e cycles -a'
|
|
|
|
--metric-only::
|
|
Only print computed metrics. Print them in a single line.
|
|
Don't show any raw values. Not supported with --per-thread.
|
|
|
|
--per-socket::
|
|
Aggregate counts per processor socket for system-wide mode measurements. This
|
|
is a useful mode to detect imbalance between sockets. To enable this mode,
|
|
use --per-socket in addition to -a. (system-wide). The output includes the
|
|
socket number and the number of online processors on that socket. This is
|
|
useful to gauge the amount of aggregation.
|
|
|
|
--per-die::
|
|
Aggregate counts per processor die for system-wide mode measurements. This
|
|
is a useful mode to detect imbalance between dies. To enable this mode,
|
|
use --per-die in addition to -a. (system-wide). The output includes the
|
|
die number and the number of online processors on that die. This is
|
|
useful to gauge the amount of aggregation.
|
|
|
|
--per-core::
|
|
Aggregate counts per physical processor for system-wide mode measurements. This
|
|
is a useful mode to detect imbalance between physical cores. To enable this mode,
|
|
use --per-core in addition to -a. (system-wide). The output includes the
|
|
core number and the number of online logical processors on that physical processor.
|
|
|
|
--per-thread::
|
|
Aggregate counts per monitored threads, when monitoring threads (-t option)
|
|
or processes (-p option).
|
|
|
|
-D msecs::
|
|
--delay msecs::
|
|
After starting the program, wait msecs before measuring. This is useful to
|
|
filter out the startup phase of the program, which is often very different.
|
|
|
|
-T::
|
|
--transaction::
|
|
|
|
Print statistics of transactional execution if supported.
|
|
|
|
STAT RECORD
|
|
-----------
|
|
Stores stat data into perf data file.
|
|
|
|
-o file::
|
|
--output file::
|
|
Output file name.
|
|
|
|
STAT REPORT
|
|
-----------
|
|
Reads and reports stat data from perf data file.
|
|
|
|
-i file::
|
|
--input file::
|
|
Input file name.
|
|
|
|
--per-socket::
|
|
Aggregate counts per processor socket for system-wide mode measurements.
|
|
|
|
--per-die::
|
|
Aggregate counts per processor die for system-wide mode measurements.
|
|
|
|
--per-core::
|
|
Aggregate counts per physical processor for system-wide mode measurements.
|
|
|
|
-M::
|
|
--metrics::
|
|
Print metrics or metricgroups specified in a comma separated list.
|
|
For a group all metrics from the group are added.
|
|
The events from the metrics are automatically measured.
|
|
See perf list output for the possble metrics and metricgroups.
|
|
|
|
-A::
|
|
--no-aggr::
|
|
Do not aggregate counts across all monitored CPUs.
|
|
|
|
--topdown::
|
|
Print top down level 1 metrics if supported by the CPU. This allows to
|
|
determine bottle necks in the CPU pipeline for CPU bound workloads,
|
|
by breaking the cycles consumed down into frontend bound, backend bound,
|
|
bad speculation and retiring.
|
|
|
|
Frontend bound means that the CPU cannot fetch and decode instructions fast
|
|
enough. Backend bound means that computation or memory access is the bottle
|
|
neck. Bad Speculation means that the CPU wasted cycles due to branch
|
|
mispredictions and similar issues. Retiring means that the CPU computed without
|
|
an apparently bottleneck. The bottleneck is only the real bottleneck
|
|
if the workload is actually bound by the CPU and not by something else.
|
|
|
|
For best results it is usually a good idea to use it with interval
|
|
mode like -I 1000, as the bottleneck of workloads can change often.
|
|
|
|
The top down metrics are collected per core instead of per
|
|
CPU thread. Per core mode is automatically enabled
|
|
and -a (global monitoring) is needed, requiring root rights or
|
|
perf.perf_event_paranoid=-1.
|
|
|
|
Topdown uses the full Performance Monitoring Unit, and needs
|
|
disabling of the NMI watchdog (as root):
|
|
echo 0 > /proc/sys/kernel/nmi_watchdog
|
|
for best results. Otherwise the bottlenecks may be inconsistent
|
|
on workload with changing phases.
|
|
|
|
This enables --metric-only, unless overridden with --no-metric-only.
|
|
|
|
To interpret the results it is usually needed to know on which
|
|
CPUs the workload runs on. If needed the CPUs can be forced using
|
|
taskset.
|
|
|
|
--no-merge::
|
|
Do not merge results from same PMUs.
|
|
|
|
When multiple events are created from a single event specification,
|
|
stat will, by default, aggregate the event counts and show the result
|
|
in a single row. This option disables that behavior and shows
|
|
the individual events and counts.
|
|
|
|
Multiple events are created from a single event specification when:
|
|
1. Prefix or glob matching is used for the PMU name.
|
|
2. Aliases, which are listed immediately after the Kernel PMU events
|
|
by perf list, are used.
|
|
|
|
--smi-cost::
|
|
Measure SMI cost if msr/aperf/ and msr/smi/ events are supported.
|
|
|
|
During the measurement, the /sys/device/cpu/freeze_on_smi will be set to
|
|
freeze core counters on SMI.
|
|
The aperf counter will not be effected by the setting.
|
|
The cost of SMI can be measured by (aperf - unhalted core cycles).
|
|
|
|
In practice, the percentages of SMI cycles is very useful for performance
|
|
oriented analysis. --metric_only will be applied by default.
|
|
The output is SMI cycles%, equals to (aperf - unhalted core cycles) / aperf
|
|
|
|
Users who wants to get the actual value can apply --no-metric-only.
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
$ perf stat -- make
|
|
|
|
Performance counter stats for 'make':
|
|
|
|
83723.452481 task-clock:u (msec) # 1.004 CPUs utilized
|
|
0 context-switches:u # 0.000 K/sec
|
|
0 cpu-migrations:u # 0.000 K/sec
|
|
3,228,188 page-faults:u # 0.039 M/sec
|
|
229,570,665,834 cycles:u # 2.742 GHz
|
|
313,163,853,778 instructions:u # 1.36 insn per cycle
|
|
69,704,684,856 branches:u # 832.559 M/sec
|
|
2,078,861,393 branch-misses:u # 2.98% of all branches
|
|
|
|
83.409183620 seconds time elapsed
|
|
|
|
74.684747000 seconds user
|
|
8.739217000 seconds sys
|
|
|
|
TIMINGS
|
|
-------
|
|
As displayed in the example above we can display 3 types of timings.
|
|
We always display the time the counters were enabled/alive:
|
|
|
|
83.409183620 seconds time elapsed
|
|
|
|
For workload sessions we also display time the workloads spent in
|
|
user/system lands:
|
|
|
|
74.684747000 seconds user
|
|
8.739217000 seconds sys
|
|
|
|
Those times are the very same as displayed by the 'time' tool.
|
|
|
|
CSV FORMAT
|
|
----------
|
|
|
|
With -x, perf stat is able to output a not-quite-CSV format output
|
|
Commas in the output are not put into "". To make it easy to parse
|
|
it is recommended to use a different character like -x \;
|
|
|
|
The fields are in this order:
|
|
|
|
- optional usec time stamp in fractions of second (with -I xxx)
|
|
- optional CPU, core, or socket identifier
|
|
- optional number of logical CPUs aggregated
|
|
- counter value
|
|
- unit of the counter value or empty
|
|
- event name
|
|
- run time of counter
|
|
- percentage of measurement time the counter was running
|
|
- optional variance if multiple values are collected with -r
|
|
- optional metric value
|
|
- optional unit of metric
|
|
|
|
Additional metrics may be printed with all earlier fields being empty.
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkperf:perf-top[1], linkperf:perf-list[1]
|