Commit | Line | Data |
---|---|---|
0a02ad93 | 1 | perf-trace(1) |
4778e0e8 | 2 | ============= |
0a02ad93 IM |
3 | |
4 | NAME | |
5 | ---- | |
6 | perf-trace - Read perf.data (created by perf record) and display trace output | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
d3c4f798 TZ |
11 | 'perf trace' [<options>] |
12 | 'perf trace' [<options>] record <script> [<record-options>] <command> | |
13 | 'perf trace' [<options>] report <script> [script-args] | |
14 | 'perf trace' [<options>] <script> <required-script-args> [<record-options>] <command> | |
15 | 'perf trace' [<options>] <top-script> [script-args] | |
0a02ad93 IM |
16 | |
17 | DESCRIPTION | |
18 | ----------- | |
19 | This command reads the input file and displays the trace recorded. | |
20 | ||
a6005123 TZ |
21 | There are several variants of perf trace: |
22 | ||
23 | 'perf trace' to see a detailed trace of the workload that was | |
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 | |
28 | available via 'perf trace -l'). The following variants allow you to | |
29 | record and run those scripts: | |
30 | ||
d3c4f798 TZ |
31 | 'perf trace record <script> <command>' to record the events required |
32 | for 'perf trace report'. <script> is the name displayed in the | |
33 | output of 'perf trace --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. | |
a6005123 | 36 | |
d3c4f798 TZ |
37 | 'perf trace report <script> [args]' to run and display the results |
38 | of <script>. <script> is the name displayed in the output of 'perf | |
a6005123 TZ |
39 | trace --list' i.e. the actual script name minus any language |
40 | extension. The perf.data output from a previous run of 'perf trace | |
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 | ||
45 | 'perf trace <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 trace --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 trace record' | |
55 | and 'perf trace 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 trace <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 trace --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 trace | |
67 | record' and 'live-mode' variants; this isn't possible however for | |
68 | <top-script> 'live-mode' or 'perf trace 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 IM |
78 | -D:: |
79 | --dump-raw-trace=:: | |
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=:: | |
98 | Generate perf-trace.[ext] starter script for given language, | |
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 | ||
107 | ||
0a02ad93 IM |
108 | SEE ALSO |
109 | -------- | |
cff68e58 TZ |
110 | linkperf:perf-record[1], linkperf:perf-trace-perl[1], |
111 | linkperf:perf-trace-python[1] |