]>
Commit | Line | Data |
---|---|---|
133dc4c3 | 1 | perf-script(1) |
4778e0e8 | 2 | ============= |
0a02ad93 IM |
3 | |
4 | NAME | |
5 | ---- | |
133dc4c3 | 6 | perf-script - Read perf.data (created by perf record) and display trace output |
0a02ad93 IM |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
133dc4c3 IM |
11 | 'perf script' [<options>] |
12 | 'perf script' [<options>] record <script> [<record-options>] <command> | |
13 | 'perf script' [<options>] report <script> [script-args] | |
14 | 'perf script' [<options>] <script> <required-script-args> [<record-options>] <command> | |
15 | 'perf script' [<options>] <top-script> [script-args] | |
0a02ad93 IM |
16 | |
17 | DESCRIPTION | |
18 | ----------- | |
19 | This command reads the input file and displays the trace recorded. | |
20 | ||
133dc4c3 | 21 | There are several variants of perf script: |
a6005123 | 22 | |
133dc4c3 | 23 | 'perf script' to see a detailed trace of the workload that was |
a6005123 TZ |
24 | recorded. |
25 | ||
cff68e58 TZ |
26 | You can also run a set of pre-canned scripts that aggregate and |
27 | summarize the raw trace data in various ways (the list of scripts is | |
133dc4c3 | 28 | available via 'perf script -l'). The following variants allow you to |
cff68e58 TZ |
29 | record and run those scripts: |
30 | ||
133dc4c3 IM |
31 | 'perf script record <script> <command>' to record the events required |
32 | for 'perf script report'. <script> is the name displayed in the | |
33 | output of 'perf script --list' i.e. the actual script name minus any | |
d3c4f798 TZ |
34 | language extension. If <command> is not specified, the events are |
35 | recorded using the -a (system-wide) 'perf record' option. | |
a6005123 | 36 | |
133dc4c3 | 37 | 'perf script report <script> [args]' to run and display the results |
d3c4f798 | 38 | of <script>. <script> is the name displayed in the output of 'perf |
a6005123 | 39 | trace --list' i.e. the actual script name minus any language |
133dc4c3 | 40 | extension. The perf.data output from a previous run of 'perf script |
a6005123 | 41 | record <script>' is used and should be present for this command to |
d3c4f798 TZ |
42 | succeed. [args] refers to the (mainly optional) args expected by |
43 | the script. | |
44 | ||
133dc4c3 | 45 | 'perf script <script> <required-script-args> <command>' to both |
d3c4f798 TZ |
46 | record the events required for <script> and to run the <script> |
47 | using 'live-mode' i.e. without writing anything to disk. <script> | |
133dc4c3 | 48 | is the name displayed in the output of 'perf script --list' i.e. the |
d3c4f798 TZ |
49 | actual script name minus any language extension. If <command> is |
50 | not specified, the events are recorded using the -a (system-wide) | |
51 | 'perf record' option. If <script> has any required args, they | |
52 | should be specified before <command>. This mode doesn't allow for | |
53 | optional script args to be specified; if optional script args are | |
133dc4c3 IM |
54 | desired, they can be specified using separate 'perf script record' |
55 | and 'perf script report' commands, with the stdout of the record step | |
d3c4f798 TZ |
56 | piped to the stdin of the report script, using the '-o -' and '-i -' |
57 | options of the corresponding commands. | |
58 | ||
133dc4c3 | 59 | 'perf script <top-script>' to both record the events required for |
d3c4f798 TZ |
60 | <top-script> and to run the <top-script> using 'live-mode' |
61 | i.e. without writing anything to disk. <top-script> is the name | |
133dc4c3 | 62 | displayed in the output of 'perf script --list' i.e. the actual |
d3c4f798 TZ |
63 | script name minus any language extension; a <top-script> is defined |
64 | as any script name ending with the string 'top'. | |
65 | ||
133dc4c3 | 66 | [<record-options>] can be passed to the record steps of 'perf script |
d3c4f798 | 67 | record' and 'live-mode' variants; this isn't possible however for |
133dc4c3 | 68 | <top-script> 'live-mode' or 'perf script report' variants. |
a6005123 | 69 | |
cff68e58 TZ |
70 | See the 'SEE ALSO' section for links to language-specific |
71 | information on how to write and run your own trace scripts. | |
72 | ||
0a02ad93 IM |
73 | OPTIONS |
74 | ------- | |
d3c4f798 TZ |
75 | <command>...:: |
76 | Any command you can specify in a shell. | |
77 | ||
0a02ad93 | 78 | -D:: |
133dc4c3 | 79 | --dump-raw-script=:: |
0a02ad93 IM |
80 | Display verbose dump of the trace data. |
81 | ||
a6005123 TZ |
82 | -L:: |
83 | --Latency=:: | |
84 | Show latency attributes (irqs/preemption disabled, etc). | |
85 | ||
86 | -l:: | |
87 | --list=:: | |
88 | Display a list of available trace scripts. | |
89 | ||
f526d68b | 90 | -s ['lang']:: |
89fbf0b8 TZ |
91 | --script=:: |
92 | Process trace data with the given script ([lang]:script[.ext]). | |
f526d68b TZ |
93 | If the string 'lang' is specified in place of a script name, a |
94 | list of supported languages will be displayed instead. | |
89fbf0b8 TZ |
95 | |
96 | -g:: | |
97 | --gen-script=:: | |
133dc4c3 | 98 | Generate perf-script.[ext] starter script for given language, |
89fbf0b8 TZ |
99 | using current perf.data. |
100 | ||
d3c4f798 TZ |
101 | -a:: |
102 | Force system-wide collection. Scripts run without a <command> | |
103 | normally use -a by default, while scripts run with a <command> | |
104 | normally don't - this option allows the latter to be run in | |
105 | system-wide mode. | |
106 | ||
646420f1 SB |
107 | -i:: |
108 | --input=:: | |
efad1415 | 109 | Input file name. (default: perf.data unless stdin is a fifo) |
646420f1 SB |
110 | |
111 | -d:: | |
112 | --debug-mode:: | |
113 | Do various checks like samples ordering and lost events. | |
d3c4f798 | 114 | |
745f43e3 | 115 | -f:: |
176fcc5c | 116 | --fields:: |
745f43e3 | 117 | Comma separated list of fields to print. Options are: |
535aeaae | 118 | comm, tid, pid, time, cpu, event, trace, ip, sym, dso, addr, symoff, srcline, period. |
7cec0922 | 119 | Field list can be prepended with the type, trace, sw or hw, |
1424dc96 | 120 | to indicate to which event type the field list applies. |
787bef17 | 121 | e.g., -f sw:comm,tid,time,ip,sym and -f trace:time,cpu,trace |
c0230b2b | 122 | |
176fcc5c ACM |
123 | perf script -f <fields> |
124 | ||
125 | is equivalent to: | |
126 | ||
127 | perf script -f trace:<fields> -f sw:<fields> -f hw:<fields> | |
48000a1a | 128 | |
176fcc5c ACM |
129 | i.e., the specified fields apply to all event types if the type string |
130 | is not given. | |
48000a1a | 131 | |
176fcc5c ACM |
132 | The arguments are processed in the order received. A later usage can |
133 | reset a prior request. e.g.: | |
48000a1a | 134 | |
787bef17 | 135 | -f trace: -f comm,tid,time,ip,sym |
48000a1a | 136 | |
176fcc5c | 137 | The first -f suppresses trace events (field list is ""), but then the |
787bef17 | 138 | second invocation sets the fields to comm,tid,time,ip,sym. In this case a |
176fcc5c | 139 | warning is given to the user: |
48000a1a | 140 | |
176fcc5c | 141 | "Overriding previous field request for all events." |
48000a1a | 142 | |
96355f2c | 143 | Alternatively, consider the order: |
48000a1a | 144 | |
787bef17 | 145 | -f comm,tid,time,ip,sym -f trace: |
48000a1a | 146 | |
176fcc5c ACM |
147 | The first -f sets the fields for all events and the second -f |
148 | suppresses trace events. The user is given a warning message about | |
149 | the override, and the result of the above is that only S/W and H/W | |
150 | events are displayed with the given fields. | |
48000a1a | 151 | |
176fcc5c ACM |
152 | For the 'wildcard' option if a user selected field is invalid for an |
153 | event type, a message is displayed to the user that the option is | |
154 | ignored for that type. For example: | |
48000a1a | 155 | |
176fcc5c ACM |
156 | $ perf script -f comm,tid,trace |
157 | 'trace' not valid for hardware events. Ignoring. | |
158 | 'trace' not valid for software events. Ignoring. | |
48000a1a | 159 | |
176fcc5c ACM |
160 | Alternatively, if the type is given an invalid field is specified it |
161 | is an error. For example: | |
48000a1a | 162 | |
176fcc5c ACM |
163 | perf script -v -f sw:comm,tid,trace |
164 | 'trace' not valid for software events. | |
48000a1a | 165 | |
176fcc5c | 166 | At this point usage is displayed, and perf-script exits. |
48000a1a | 167 | |
176fcc5c ACM |
168 | Finally, a user may not set fields to none for all event types. |
169 | i.e., -f "" is not allowed. | |
170 | ||
c0230b2b DA |
171 | -k:: |
172 | --vmlinux=<file>:: | |
173 | vmlinux pathname | |
174 | ||
175 | --kallsyms=<file>:: | |
176 | kallsyms pathname | |
177 | ||
178 | --symfs=<directory>:: | |
179 | Look for files with symbols relative to this directory. | |
180 | ||
181 | -G:: | |
182 | --hide-call-graph:: | |
183 | When printing symbols do not display call chain. | |
745f43e3 | 184 | |
c8e66720 | 185 | -C:: |
5d67be97 AB |
186 | --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can |
187 | be provided as a comma-separated list with no space: 0,1. Ranges of | |
188 | CPUs are specified with -: 0-2. Default is to report samples on all | |
189 | CPUs. | |
190 | ||
e7984b7b DA |
191 | -c:: |
192 | --comms=:: | |
193 | Only display events for these comms. CSV that understands | |
194 | file://filename entries. | |
195 | ||
e03eaa40 DA |
196 | --pid=:: |
197 | Only show events for given process ID (comma separated list). | |
198 | ||
199 | --tid=:: | |
200 | Only show events for given thread ID (comma separated list). | |
201 | ||
fbe96f29 SE |
202 | -I:: |
203 | --show-info:: | |
204 | Display extended information about the perf.data file. This adds | |
205 | information which may be very large and thus may clutter the display. | |
206 | It currently includes: cpu and numa topology of the host system. | |
207 | It can only be used with the perf script report mode. | |
208 | ||
0bc8d205 AN |
209 | --show-kernel-path:: |
210 | Try to resolve the path of [kernel.kallsyms] | |
211 | ||
ad7ebb9a NK |
212 | --show-task-events |
213 | Display task related events (e.g. FORK, COMM, EXIT). | |
214 | ||
ba1ddf42 NK |
215 | --show-mmap-events |
216 | Display mmap related events (e.g. MMAP, MMAP2). | |
217 | ||
e90debdd JO |
218 | --header |
219 | Show perf.data header. | |
220 | ||
221 | --header-only | |
222 | Show only perf.data header. | |
223 | ||
0a02ad93 IM |
224 | SEE ALSO |
225 | -------- | |
133dc4c3 IM |
226 | linkperf:perf-record[1], linkperf:perf-script-perl[1], |
227 | linkperf:perf-script-python[1] |