210 lines
7.1 KiB
Plaintext
210 lines
7.1 KiB
Plaintext
perf-script(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
perf-script - Read perf.data (created by perf record) and display trace output
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'perf script' [<options>]
|
|
'perf script' [<options>] record <script> [<record-options>] <command>
|
|
'perf script' [<options>] report <script> [script-args]
|
|
'perf script' [<options>] <script> <required-script-args> [<record-options>] <command>
|
|
'perf script' [<options>] <top-script> [script-args]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
This command reads the input file and displays the trace recorded.
|
|
|
|
There are several variants of perf script:
|
|
|
|
'perf script' to see a detailed trace of the workload that was
|
|
recorded.
|
|
|
|
You can also run a set of pre-canned scripts that aggregate and
|
|
summarize the raw trace data in various ways (the list of scripts is
|
|
available via 'perf script -l'). The following variants allow you to
|
|
record and run those scripts:
|
|
|
|
'perf script record <script> <command>' to record the events required
|
|
for 'perf script report'. <script> is the name displayed in the
|
|
output of 'perf script --list' i.e. the actual script name minus any
|
|
language extension. If <command> is not specified, the events are
|
|
recorded using the -a (system-wide) 'perf record' option.
|
|
|
|
'perf script report <script> [args]' to run and display the results
|
|
of <script>. <script> is the name displayed in the output of 'perf
|
|
trace --list' i.e. the actual script name minus any language
|
|
extension. The perf.data output from a previous run of 'perf script
|
|
record <script>' is used and should be present for this command to
|
|
succeed. [args] refers to the (mainly optional) args expected by
|
|
the script.
|
|
|
|
'perf script <script> <required-script-args> <command>' to both
|
|
record the events required for <script> and to run the <script>
|
|
using 'live-mode' i.e. without writing anything to disk. <script>
|
|
is the name displayed in the output of 'perf script --list' i.e. the
|
|
actual script name minus any language extension. If <command> is
|
|
not specified, the events are recorded using the -a (system-wide)
|
|
'perf record' option. If <script> has any required args, they
|
|
should be specified before <command>. This mode doesn't allow for
|
|
optional script args to be specified; if optional script args are
|
|
desired, they can be specified using separate 'perf script record'
|
|
and 'perf script report' commands, with the stdout of the record step
|
|
piped to the stdin of the report script, using the '-o -' and '-i -'
|
|
options of the corresponding commands.
|
|
|
|
'perf script <top-script>' to both record the events required for
|
|
<top-script> and to run the <top-script> using 'live-mode'
|
|
i.e. without writing anything to disk. <top-script> is the name
|
|
displayed in the output of 'perf script --list' i.e. the actual
|
|
script name minus any language extension; a <top-script> is defined
|
|
as any script name ending with the string 'top'.
|
|
|
|
[<record-options>] can be passed to the record steps of 'perf script
|
|
record' and 'live-mode' variants; this isn't possible however for
|
|
<top-script> 'live-mode' or 'perf script report' variants.
|
|
|
|
See the 'SEE ALSO' section for links to language-specific
|
|
information on how to write and run your own trace scripts.
|
|
|
|
OPTIONS
|
|
-------
|
|
<command>...::
|
|
Any command you can specify in a shell.
|
|
|
|
-D::
|
|
--dump-raw-script=::
|
|
Display verbose dump of the trace data.
|
|
|
|
-L::
|
|
--Latency=::
|
|
Show latency attributes (irqs/preemption disabled, etc).
|
|
|
|
-l::
|
|
--list=::
|
|
Display a list of available trace scripts.
|
|
|
|
-s ['lang']::
|
|
--script=::
|
|
Process trace data with the given script ([lang]:script[.ext]).
|
|
If the string 'lang' is specified in place of a script name, a
|
|
list of supported languages will be displayed instead.
|
|
|
|
-g::
|
|
--gen-script=::
|
|
Generate perf-script.[ext] starter script for given language,
|
|
using current perf.data.
|
|
|
|
-a::
|
|
Force system-wide collection. Scripts run without a <command>
|
|
normally use -a by default, while scripts run with a <command>
|
|
normally don't - this option allows the latter to be run in
|
|
system-wide mode.
|
|
|
|
-i::
|
|
--input=::
|
|
Input file name. (default: perf.data unless stdin is a fifo)
|
|
|
|
-d::
|
|
--debug-mode::
|
|
Do various checks like samples ordering and lost events.
|
|
|
|
-f::
|
|
--fields::
|
|
Comma separated list of fields to print. Options are:
|
|
comm, tid, pid, time, cpu, event, trace, ip, sym, dso, addr, symoff.
|
|
Field list can be prepended with the type, trace, sw or hw,
|
|
to indicate to which event type the field list applies.
|
|
e.g., -f sw:comm,tid,time,ip,sym and -f trace:time,cpu,trace
|
|
|
|
perf script -f <fields>
|
|
|
|
is equivalent to:
|
|
|
|
perf script -f trace:<fields> -f sw:<fields> -f hw:<fields>
|
|
|
|
i.e., the specified fields apply to all event types if the type string
|
|
is not given.
|
|
|
|
The arguments are processed in the order received. A later usage can
|
|
reset a prior request. e.g.:
|
|
|
|
-f trace: -f comm,tid,time,ip,sym
|
|
|
|
The first -f suppresses trace events (field list is ""), but then the
|
|
second invocation sets the fields to comm,tid,time,ip,sym. In this case a
|
|
warning is given to the user:
|
|
|
|
"Overriding previous field request for all events."
|
|
|
|
Alternativey, consider the order:
|
|
|
|
-f comm,tid,time,ip,sym -f trace:
|
|
|
|
The first -f sets the fields for all events and the second -f
|
|
suppresses trace events. The user is given a warning message about
|
|
the override, and the result of the above is that only S/W and H/W
|
|
events are displayed with the given fields.
|
|
|
|
For the 'wildcard' option if a user selected field is invalid for an
|
|
event type, a message is displayed to the user that the option is
|
|
ignored for that type. For example:
|
|
|
|
$ perf script -f comm,tid,trace
|
|
'trace' not valid for hardware events. Ignoring.
|
|
'trace' not valid for software events. Ignoring.
|
|
|
|
Alternatively, if the type is given an invalid field is specified it
|
|
is an error. For example:
|
|
|
|
perf script -v -f sw:comm,tid,trace
|
|
'trace' not valid for software events.
|
|
|
|
At this point usage is displayed, and perf-script exits.
|
|
|
|
Finally, a user may not set fields to none for all event types.
|
|
i.e., -f "" is not allowed.
|
|
|
|
-k::
|
|
--vmlinux=<file>::
|
|
vmlinux pathname
|
|
|
|
--kallsyms=<file>::
|
|
kallsyms pathname
|
|
|
|
--symfs=<directory>::
|
|
Look for files with symbols relative to this directory.
|
|
|
|
-G::
|
|
--hide-call-graph::
|
|
When printing symbols do not display call chain.
|
|
|
|
-C::
|
|
--cpu:: Only report samples for 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. Default is to report samples on all
|
|
CPUs.
|
|
|
|
-c::
|
|
--comms=::
|
|
Only display events for these comms. CSV that understands
|
|
file://filename entries.
|
|
|
|
-I::
|
|
--show-info::
|
|
Display extended information about the perf.data file. This adds
|
|
information which may be very large and thus may clutter the display.
|
|
It currently includes: cpu and numa topology of the host system.
|
|
It can only be used with the perf script report mode.
|
|
|
|
--show-kernel-path::
|
|
Try to resolve the path of [kernel.kallsyms]
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkperf:perf-record[1], linkperf:perf-script-perl[1],
|
|
linkperf:perf-script-python[1]
|