1 perf-ftrace(1) 1 perf-ftrace(1)
2 ============== 2 ==============
3 3
4 NAME 4 NAME
5 ---- 5 ----
6 perf-ftrace - simple wrapper for kernel's ftra 6 perf-ftrace - simple wrapper for kernel's ftrace functionality
7 7
8 8
9 SYNOPSIS 9 SYNOPSIS
10 -------- 10 --------
11 [verse] 11 [verse]
12 'perf ftrace' {trace|latency|profile} <command !! 12 'perf ftrace' {trace|latency} <command>
13 13
14 DESCRIPTION 14 DESCRIPTION
15 ----------- 15 -----------
16 The 'perf ftrace' command provides a collectio 16 The 'perf ftrace' command provides a collection of subcommands which use
17 kernel's ftrace infrastructure. 17 kernel's ftrace infrastructure.
18 18
19 'perf ftrace trace' is a simple wrapper of t 19 'perf ftrace trace' is a simple wrapper of the ftrace. It only supports
20 single thread tracing currently and just rea 20 single thread tracing currently and just reads trace_pipe in text and then
21 write it to stdout. 21 write it to stdout.
22 22
23 'perf ftrace latency' calculates execution l 23 'perf ftrace latency' calculates execution latency of a given function
24 (optionally with BPF) and display it as a hi 24 (optionally with BPF) and display it as a histogram.
25 25
26 'perf ftrace profile' show a execution profi <<
27 total, average, max time and the number of c <<
28 <<
29 The following options apply to perf ftrace. 26 The following options apply to perf ftrace.
30 27
31 COMMON OPTIONS 28 COMMON OPTIONS
32 -------------- 29 --------------
33 30
34 -p:: 31 -p::
35 --pid=:: 32 --pid=::
36 Trace on existing process id (comma se 33 Trace on existing process id (comma separated list).
37 34
38 --tid=:: 35 --tid=::
39 Trace on existing thread id (comma sep 36 Trace on existing thread id (comma separated list).
40 37
41 -a:: 38 -a::
42 --all-cpus:: 39 --all-cpus::
43 Force system-wide collection. Scripts 40 Force system-wide collection. Scripts run without a <command>
44 normally use -a by default, while scri 41 normally use -a by default, while scripts run with a <command>
45 normally don't - this option allows th 42 normally don't - this option allows the latter to be run in
46 system-wide mode. 43 system-wide mode.
47 44
48 -C:: 45 -C::
49 --cpu=:: 46 --cpu=::
50 Only trace for the list of CPUs provid 47 Only trace for the list of CPUs provided. Multiple CPUs can
51 be provided as a comma separated list 48 be provided as a comma separated list with no space like: 0,1.
52 Ranges of CPUs are specified with -: 0 49 Ranges of CPUs are specified with -: 0-2.
53 Default is to trace on all online CPUs 50 Default is to trace on all online CPUs.
54 51
55 -v:: 52 -v::
56 --verbose:: 53 --verbose::
57 Increase the verbosity level. 54 Increase the verbosity level.
58 55
59 56
60 OPTIONS for 'perf ftrace trace' 57 OPTIONS for 'perf ftrace trace'
61 ------------------------------- 58 -------------------------------
62 59
63 -t:: 60 -t::
64 --tracer=:: 61 --tracer=::
65 Tracer to use when neither -G nor -F o 62 Tracer to use when neither -G nor -F option is not
66 specified: function_graph or function. 63 specified: function_graph or function.
67 64
68 -F:: 65 -F::
69 --funcs:: 66 --funcs::
70 List available functions to trace. It 67 List available functions to trace. It accepts a pattern to
71 only list interested functions. 68 only list interested functions.
72 69
73 -D:: 70 -D::
74 --delay:: 71 --delay::
75 Time (ms) to wait before starting trac 72 Time (ms) to wait before starting tracing after program start.
76 73
77 -m:: 74 -m::
78 --buffer-size:: 75 --buffer-size::
79 Set the size of per-cpu tracing buffer 76 Set the size of per-cpu tracing buffer, <size> is expected to
80 be a number with appended unit charact 77 be a number with appended unit character - B/K/M/G.
81 78
82 --inherit:: 79 --inherit::
83 Trace children processes spawned by ou 80 Trace children processes spawned by our target.
84 81
85 -T:: 82 -T::
86 --trace-funcs=:: 83 --trace-funcs=::
87 Select function tracer and set functio 84 Select function tracer and set function filter on the given
88 function (or a glob pattern). Multiple 85 function (or a glob pattern). Multiple functions can be given
89 by using this option more than once. T 86 by using this option more than once. The function argument also
90 can be a glob pattern. It will be pass 87 can be a glob pattern. It will be passed to 'set_ftrace_filter'
91 in tracefs. 88 in tracefs.
92 89
93 -N:: 90 -N::
94 --notrace-funcs=:: 91 --notrace-funcs=::
95 Select function tracer and do not trac 92 Select function tracer and do not trace functions given by the
96 argument. Like -T option, this can be 93 argument. Like -T option, this can be used more than once to
97 specify multiple functions (or glob pa 94 specify multiple functions (or glob patterns). It will be
98 passed to 'set_ftrace_notrace' in trac 95 passed to 'set_ftrace_notrace' in tracefs.
99 96
100 --func-opts:: 97 --func-opts::
101 List of options allowed to set: 98 List of options allowed to set:
102 99
103 - call-graph - Display kernel stack 100 - call-graph - Display kernel stack trace for function tracer.
104 - irq-info - Display irq context i 101 - irq-info - Display irq context info for function tracer.
105 102
106 -G:: 103 -G::
107 --graph-funcs=:: 104 --graph-funcs=::
108 Select function_graph tracer and set g 105 Select function_graph tracer and set graph filter on the given
109 function (or a glob pattern). This is 106 function (or a glob pattern). This is useful to trace for
110 functions executed from the given func 107 functions executed from the given function. This can be used more
111 than once to specify multiple function 108 than once to specify multiple functions. It will be passed to
112 'set_graph_function' in tracefs. 109 'set_graph_function' in tracefs.
113 110
114 -g:: 111 -g::
115 --nograph-funcs=:: 112 --nograph-funcs=::
116 Select function_graph tracer and set g 113 Select function_graph tracer and set graph notrace filter on the
117 given function (or a glob pattern). Li 114 given function (or a glob pattern). Like -G option, this is useful
118 for the function_graph tracer only and 115 for the function_graph tracer only and disables tracing for function
119 executed from the given function. This 116 executed from the given function. This can be used more than once to
120 specify multiple functions. It will be 117 specify multiple functions. It will be passed to 'set_graph_notrace'
121 in tracefs. 118 in tracefs.
122 119
123 --graph-opts:: 120 --graph-opts::
124 List of options allowed to set: 121 List of options allowed to set:
125 122
126 - nosleep-time - Measure on-CPU time 123 - nosleep-time - Measure on-CPU time only for function_graph tracer.
127 - noirqs - Ignore functions th 124 - noirqs - Ignore functions that happen inside interrupt.
128 - verbose - Show process names, 125 - verbose - Show process names, PIDs, timestamps, etc.
129 - thresh=<n> - Setup trace duratio 126 - thresh=<n> - Setup trace duration threshold in microseconds.
130 - depth=<n> - Set max depth for f 127 - depth=<n> - Set max depth for function graph tracer to follow.
131 - tail - Print function name <<
132 128
133 129
134 OPTIONS for 'perf ftrace latency' 130 OPTIONS for 'perf ftrace latency'
135 --------------------------------- 131 ---------------------------------
136 132
137 -T:: 133 -T::
138 --trace-funcs=:: 134 --trace-funcs=::
139 Set the function name to get the histo 135 Set the function name to get the histogram. Unlike perf ftrace trace,
140 it only allows single function to calc 136 it only allows single function to calculate the histogram.
141 137
142 -b:: 138 -b::
143 --use-bpf:: 139 --use-bpf::
144 Use BPF to measure function latency in 140 Use BPF to measure function latency instead of using the ftrace (it
145 uses function_graph tracer internally) 141 uses function_graph tracer internally).
146 142
147 -n:: 143 -n::
148 --use-nsec:: 144 --use-nsec::
149 Use nano-second instead of micro-secon 145 Use nano-second instead of micro-second as a base unit of the histogram.
150 <<
151 <<
152 OPTIONS for 'perf ftrace profile' <<
153 --------------------------------- <<
154 <<
155 -T:: <<
156 --trace-funcs=:: <<
157 Set function filter on the given funct <<
158 Multiple functions can be given by usi <<
159 The function argument also can be a gl <<
160 to 'set_ftrace_filter' in tracefs. <<
161 <<
162 -N:: <<
163 --notrace-funcs=:: <<
164 Do not trace functions given by the ar <<
165 can be used more than once to specify <<
166 patterns). It will be passed to 'set_ <<
167 <<
168 -G:: <<
169 --graph-funcs=:: <<
170 Set graph filter on the given function <<
171 useful to trace for functions executed <<
172 can be used more than once to specify <<
173 passed to 'set_graph_function' in trac <<
174 <<
175 -g:: <<
176 --nograph-funcs=:: <<
177 Set graph notrace filter on the given <<
178 Like -G option, this is useful for the <<
179 disables tracing for function executed <<
180 can be used more than once to specify <<
181 passed to 'set_graph_notrace' in trace <<
182 <<
183 -m:: <<
184 --buffer-size:: <<
185 Set the size of per-cpu tracing buffer <<
186 be a number with appended unit charact <<
187 <<
188 -s:: <<
189 --sort=:: <<
190 Sort the result by the given field. A <<
191 total, avg, max, count, name. Default <<
192 146
193 147
194 SEE ALSO 148 SEE ALSO
195 -------- 149 --------
196 linkperf:perf-record[1], linkperf:perf-trace[1 150 linkperf:perf-record[1], linkperf:perf-trace[1]
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.