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 call-graph - Display kernel stack trace for function tracer.
103 - call-graph - Display kernel stack !! 100 irq-info - Display irq context info for function tracer.
104 - irq-info - Display irq context i <<
105 101
106 -G:: 102 -G::
107 --graph-funcs=:: 103 --graph-funcs=::
108 Select function_graph tracer and set g 104 Select function_graph tracer and set graph filter on the given
109 function (or a glob pattern). This is 105 function (or a glob pattern). This is useful to trace for
110 functions executed from the given func 106 functions executed from the given function. This can be used more
111 than once to specify multiple function 107 than once to specify multiple functions. It will be passed to
112 'set_graph_function' in tracefs. 108 'set_graph_function' in tracefs.
113 109
114 -g:: 110 -g::
115 --nograph-funcs=:: 111 --nograph-funcs=::
116 Select function_graph tracer and set g 112 Select function_graph tracer and set graph notrace filter on the
117 given function (or a glob pattern). Li 113 given function (or a glob pattern). Like -G option, this is useful
118 for the function_graph tracer only and 114 for the function_graph tracer only and disables tracing for function
119 executed from the given function. This 115 executed from the given function. This can be used more than once to
120 specify multiple functions. It will be 116 specify multiple functions. It will be passed to 'set_graph_notrace'
121 in tracefs. 117 in tracefs.
122 118
123 --graph-opts:: 119 --graph-opts::
124 List of options allowed to set: 120 List of options allowed to set:
125 !! 121 nosleep-time - Measure on-CPU time only for function_graph tracer.
126 - nosleep-time - Measure on-CPU time !! 122 noirqs - Ignore functions that happen inside interrupt.
127 - noirqs - Ignore functions th !! 123 verbose - Show process names, PIDs, timestamps, etc.
128 - verbose - Show process names, !! 124 thresh=<n> - Setup trace duration threshold in microseconds.
129 - thresh=<n> - Setup trace duratio !! 125 depth=<n> - Set max depth for function graph tracer to follow.
130 - depth=<n> - Set max depth for f <<
131 - tail - Print function name <<
132 126
133 127
134 OPTIONS for 'perf ftrace latency' 128 OPTIONS for 'perf ftrace latency'
135 --------------------------------- 129 ---------------------------------
136 130
137 -T:: 131 -T::
138 --trace-funcs=:: 132 --trace-funcs=::
139 Set the function name to get the histo 133 Set the function name to get the histogram. Unlike perf ftrace trace,
140 it only allows single function to calc 134 it only allows single function to calculate the histogram.
141 135
142 -b:: 136 -b::
143 --use-bpf:: 137 --use-bpf::
144 Use BPF to measure function latency in 138 Use BPF to measure function latency instead of using the ftrace (it
145 uses function_graph tracer internally) 139 uses function_graph tracer internally).
146 140
147 -n:: 141 -n::
148 --use-nsec:: 142 --use-nsec::
149 Use nano-second instead of micro-secon 143 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 144
193 145
194 SEE ALSO 146 SEE ALSO
195 -------- 147 --------
196 linkperf:perf-record[1], linkperf:perf-trace[1 148 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.