PERF-SCRIPT(1) perf Manual PERF-SCRIPT(1)NAMEperf-script - Read perf.data (created by perf record) and display trace
output
SYNOPSIS
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 ALSOperf-record(1), perf-script-perl(1), perf-script-python(1)perf 11/21/2013 PERF-SCRIPT(1)