]>
Commit | Line | Data |
---|---|---|
1 | perf-script(1) | |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | perf-script - Read perf.data (created by perf record) and display trace output | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
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] | |
16 | ||
17 | DESCRIPTION | |
18 | ----------- | |
19 | This command reads the input file and displays the trace recorded. | |
20 | ||
21 | There are several variants of perf script: | |
22 | ||
23 | 'perf script' to see a detailed trace of the workload that was | |
24 | recorded. | |
25 | ||
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 | |
28 | available via 'perf script -l'). The following variants allow you to | |
29 | record and run those scripts: | |
30 | ||
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 | |
34 | language extension. If <command> is not specified, the events are | |
35 | recorded using the -a (system-wide) 'perf record' option. | |
36 | ||
37 | 'perf script report <script> [args]' to run and display the results | |
38 | of <script>. <script> is the name displayed in the output of 'perf | |
39 | trace --list' i.e. the actual script name minus any language | |
40 | extension. The perf.data output from a previous run of 'perf script | |
41 | record <script>' is used and should be present for this command to | |
42 | succeed. [args] refers to the (mainly optional) args expected by | |
43 | the script. | |
44 | ||
45 | 'perf script <script> <required-script-args> <command>' to both | |
46 | record the events required for <script> and to run the <script> | |
47 | using 'live-mode' i.e. without writing anything to disk. <script> | |
48 | is the name displayed in the output of 'perf script --list' i.e. the | |
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 | |
54 | desired, they can be specified using separate 'perf script record' | |
55 | and 'perf script report' commands, with the stdout of the record step | |
56 | piped to the stdin of the report script, using the '-o -' and '-i -' | |
57 | options of the corresponding commands. | |
58 | ||
59 | 'perf script <top-script>' to both record the events required for | |
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 | |
62 | displayed in the output of 'perf script --list' i.e. the actual | |
63 | script name minus any language extension; a <top-script> is defined | |
64 | as any script name ending with the string 'top'. | |
65 | ||
66 | [<record-options>] can be passed to the record steps of 'perf script | |
67 | record' and 'live-mode' variants; this isn't possible however for | |
68 | <top-script> 'live-mode' or 'perf script report' variants. | |
69 | ||
70 | See the 'SEE ALSO' section for links to language-specific | |
71 | information on how to write and run your own trace scripts. | |
72 | ||
73 | OPTIONS | |
74 | ------- | |
75 | <command>...:: | |
76 | Any command you can specify in a shell. | |
77 | ||
78 | -D:: | |
79 | --dump-raw-script=:: | |
80 | Display verbose dump of the trace data. | |
81 | ||
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 | ||
90 | -s ['lang']:: | |
91 | --script=:: | |
92 | Process trace data with the given script ([lang]:script[.ext]). | |
93 | If the string 'lang' is specified in place of a script name, a | |
94 | list of supported languages will be displayed instead. | |
95 | ||
96 | -g:: | |
97 | --gen-script=:: | |
98 | Generate perf-script.[ext] starter script for given language, | |
99 | using current perf.data. | |
100 | ||
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 | ||
107 | -i:: | |
108 | --input=:: | |
109 | Input file name. (default: perf.data unless stdin is a fifo) | |
110 | ||
111 | -d:: | |
112 | --debug-mode:: | |
113 | Do various checks like samples ordering and lost events. | |
114 | ||
115 | -F:: | |
116 | --fields:: | |
117 | Comma separated list of fields to print. Options are: | |
118 | comm, tid, pid, time, cpu, event, trace, ip, sym, dso, addr, symoff, | |
119 | srcline, period, iregs, brstack, brstacksym, flags, bpf-output, | |
120 | callindent. Field list can be prepended with the type, trace, sw or hw, | |
121 | to indicate to which event type the field list applies. | |
122 | e.g., -F sw:comm,tid,time,ip,sym and -F trace:time,cpu,trace | |
123 | ||
124 | perf script -F <fields> | |
125 | ||
126 | is equivalent to: | |
127 | ||
128 | perf script -F trace:<fields> -F sw:<fields> -F hw:<fields> | |
129 | ||
130 | i.e., the specified fields apply to all event types if the type string | |
131 | is not given. | |
132 | ||
133 | The arguments are processed in the order received. A later usage can | |
134 | reset a prior request. e.g.: | |
135 | ||
136 | -F trace: -F comm,tid,time,ip,sym | |
137 | ||
138 | The first -F suppresses trace events (field list is ""), but then the | |
139 | second invocation sets the fields to comm,tid,time,ip,sym. In this case a | |
140 | warning is given to the user: | |
141 | ||
142 | "Overriding previous field request for all events." | |
143 | ||
144 | Alternatively, consider the order: | |
145 | ||
146 | -F comm,tid,time,ip,sym -F trace: | |
147 | ||
148 | The first -F sets the fields for all events and the second -F | |
149 | suppresses trace events. The user is given a warning message about | |
150 | the override, and the result of the above is that only S/W and H/W | |
151 | events are displayed with the given fields. | |
152 | ||
153 | For the 'wildcard' option if a user selected field is invalid for an | |
154 | event type, a message is displayed to the user that the option is | |
155 | ignored for that type. For example: | |
156 | ||
157 | $ perf script -F comm,tid,trace | |
158 | 'trace' not valid for hardware events. Ignoring. | |
159 | 'trace' not valid for software events. Ignoring. | |
160 | ||
161 | Alternatively, if the type is given an invalid field is specified it | |
162 | is an error. For example: | |
163 | ||
164 | perf script -v -F sw:comm,tid,trace | |
165 | 'trace' not valid for software events. | |
166 | ||
167 | At this point usage is displayed, and perf-script exits. | |
168 | ||
169 | The flags field is synthesized and may have a value when Instruction | |
170 | Trace decoding. The flags are "bcrosyiABEx" which stand for branch, | |
171 | call, return, conditional, system, asynchronous, interrupt, | |
172 | transaction abort, trace begin, trace end, and in transaction, | |
173 | respectively. Known combinations of flags are printed more nicely e.g. | |
174 | "call" for "bc", "return" for "br", "jcc" for "bo", "jmp" for "b", | |
175 | "int" for "bci", "iret" for "bri", "syscall" for "bcs", "sysret" for "brs", | |
176 | "async" for "by", "hw int" for "bcyi", "tx abrt" for "bA", "tr strt" for "bB", | |
177 | "tr end" for "bE". However the "x" flag will be display separately in those | |
178 | cases e.g. "jcc (x)" for a condition branch within a transaction. | |
179 | ||
180 | The callindent field is synthesized and may have a value when | |
181 | Instruction Trace decoding. For calls and returns, it will display the | |
182 | name of the symbol indented with spaces to reflect the stack depth. | |
183 | ||
184 | Finally, a user may not set fields to none for all event types. | |
185 | i.e., -F "" is not allowed. | |
186 | ||
187 | The brstack output includes branch related information with raw addresses using the | |
188 | /v/v/v/v/ syntax in the following order: | |
189 | FROM: branch source instruction | |
190 | TO : branch target instruction | |
191 | M/P/-: M=branch target mispredicted or branch direction was mispredicted, P=target predicted or direction predicted, -=not supported | |
192 | X/- : X=branch inside a transactional region, -=not in transaction region or not supported | |
193 | A/- : A=TSX abort entry, -=not aborted region or not supported | |
194 | ||
195 | The brstacksym is identical to brstack, except that the FROM and TO addresses are printed in a symbolic form if possible. | |
196 | ||
197 | -k:: | |
198 | --vmlinux=<file>:: | |
199 | vmlinux pathname | |
200 | ||
201 | --kallsyms=<file>:: | |
202 | kallsyms pathname | |
203 | ||
204 | --symfs=<directory>:: | |
205 | Look for files with symbols relative to this directory. | |
206 | ||
207 | -G:: | |
208 | --hide-call-graph:: | |
209 | When printing symbols do not display call chain. | |
210 | ||
211 | -C:: | |
212 | --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can | |
213 | be provided as a comma-separated list with no space: 0,1. Ranges of | |
214 | CPUs are specified with -: 0-2. Default is to report samples on all | |
215 | CPUs. | |
216 | ||
217 | -c:: | |
218 | --comms=:: | |
219 | Only display events for these comms. CSV that understands | |
220 | file://filename entries. | |
221 | ||
222 | --pid=:: | |
223 | Only show events for given process ID (comma separated list). | |
224 | ||
225 | --tid=:: | |
226 | Only show events for given thread ID (comma separated list). | |
227 | ||
228 | -I:: | |
229 | --show-info:: | |
230 | Display extended information about the perf.data file. This adds | |
231 | information which may be very large and thus may clutter the display. | |
232 | It currently includes: cpu and numa topology of the host system. | |
233 | It can only be used with the perf script report mode. | |
234 | ||
235 | --show-kernel-path:: | |
236 | Try to resolve the path of [kernel.kallsyms] | |
237 | ||
238 | --show-task-events | |
239 | Display task related events (e.g. FORK, COMM, EXIT). | |
240 | ||
241 | --show-mmap-events | |
242 | Display mmap related events (e.g. MMAP, MMAP2). | |
243 | ||
244 | --show-switch-events | |
245 | Display context switch events i.e. events of type PERF_RECORD_SWITCH or | |
246 | PERF_RECORD_SWITCH_CPU_WIDE. | |
247 | ||
248 | --demangle:: | |
249 | Demangle symbol names to human readable form. It's enabled by default, | |
250 | disable with --no-demangle. | |
251 | ||
252 | --demangle-kernel:: | |
253 | Demangle kernel symbol names to human readable form (for C++ kernels). | |
254 | ||
255 | --header | |
256 | Show perf.data header. | |
257 | ||
258 | --header-only | |
259 | Show only perf.data header. | |
260 | ||
261 | --itrace:: | |
262 | Options for decoding instruction tracing data. The options are: | |
263 | ||
264 | include::itrace.txt[] | |
265 | ||
266 | To disable decoding entirely, use --no-itrace. | |
267 | ||
268 | --full-source-path:: | |
269 | Show the full path for source files for srcline output. | |
270 | ||
271 | --max-stack:: | |
272 | Set the stack depth limit when parsing the callchain, anything | |
273 | beyond the specified depth will be ignored. This is a trade-off | |
274 | between information loss and faster processing especially for | |
275 | workloads that can have a very long callchain stack. | |
276 | Note that when using the --itrace option the synthesized callchain size | |
277 | will override this value if the synthesized callchain size is bigger. | |
278 | ||
279 | Default: 127 | |
280 | ||
281 | --ns:: | |
282 | Use 9 decimal places when displaying time (i.e. show the nanoseconds) | |
283 | ||
284 | -f:: | |
285 | --force:: | |
286 | Don't do ownership validation. | |
287 | ||
288 | SEE ALSO | |
289 | -------- | |
290 | linkperf:perf-record[1], linkperf:perf-script-perl[1], | |
291 | linkperf:perf-script-python[1] |