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