table of contents
PERF-SCRIPT(1) | perf Manual | PERF-SCRIPT(1) |
NAME¶
perf-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, srcline,
period. 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."
Alternatively, 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.
--pid=
Only show events for given process ID (comma separated
list).
--tid=
Only show events for given thread ID (comma separated
list).
-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]
--show-task-events Display task related events (e.g. FORK, COMM, EXIT).
--show-mmap-events Display mmap related events (e.g. MMAP, MMAP2).
--header Show perf.data header.
--header-only Show only perf.data header.
--full-source-path
Show the full path for source files for srcline
output.
SEE ALSO¶
05/02/2024 | perf |