Commit | Line | Data |
---|---|---|
47781947 MH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ================= | |
4 | Boot-time tracing | |
5 | ================= | |
6 | ||
7 | :Author: Masami Hiramatsu <mhiramat@kernel.org> | |
8 | ||
9 | Overview | |
10 | ======== | |
11 | ||
12 | Boot-time tracing allows users to trace boot-time process including | |
13 | device initialization with full features of ftrace including per-event | |
14 | filter and actions, histograms, kprobe-events and synthetic-events, | |
15 | and trace instances. | |
b8381ce7 | 16 | Since kernel command line is not enough to control these complex features, |
47781947 MH |
17 | this uses bootconfig file to describe tracing feature programming. |
18 | ||
19 | Options in the Boot Config | |
20 | ========================== | |
21 | ||
22 | Here is the list of available options list for boot time tracing in | |
23 | boot config file [1]_. All options are under "ftrace." or "kernel." | |
b8381ce7 | 24 | prefix. See kernel parameters for the options which starts |
47781947 MH |
25 | with "kernel." prefix [2]_. |
26 | ||
27 | .. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>` | |
28 | .. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` | |
29 | ||
30 | Ftrace Global Options | |
31 | --------------------- | |
32 | ||
33 | Ftrace global options have "kernel." prefix in boot config, which means | |
34 | these options are passed as a part of kernel legacy command line. | |
35 | ||
36 | kernel.tp_printk | |
37 | Output trace-event data on printk buffer too. | |
38 | ||
39 | kernel.dump_on_oops [= MODE] | |
40 | Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer | |
41 | on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops. | |
42 | ||
43 | kernel.traceoff_on_warning | |
44 | Stop tracing if WARN_ON() occurs. | |
45 | ||
46 | kernel.fgraph_max_depth = MAX_DEPTH | |
47 | Set MAX_DEPTH to maximum depth of fgraph tracer. | |
48 | ||
49 | kernel.fgraph_filters = FILTER[, FILTER2...] | |
50 | Add fgraph tracing function filters. | |
51 | ||
52 | kernel.fgraph_notraces = FILTER[, FILTER2...] | |
b8381ce7 | 53 | Add fgraph non-tracing function filters. |
47781947 MH |
54 | |
55 | ||
56 | Ftrace Per-instance Options | |
57 | --------------------------- | |
58 | ||
59 | These options can be used for each instance including global ftrace node. | |
60 | ||
61 | ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]] | |
62 | Enable given ftrace options. | |
63 | ||
c51ba517 MH |
64 | ftrace.[instance.INSTANCE.]tracing_on = 0|1 |
65 | Enable/Disable tracing on this instance when starting boot-time tracing. | |
66 | (you can enable it by the "traceon" event trigger action) | |
67 | ||
47781947 MH |
68 | ftrace.[instance.INSTANCE.]trace_clock = CLOCK |
69 | Set given CLOCK to ftrace's trace_clock. | |
70 | ||
71 | ftrace.[instance.INSTANCE.]buffer_size = SIZE | |
72 | Configure ftrace buffer size to SIZE. You can use "KB" or "MB" | |
73 | for that SIZE. | |
74 | ||
75 | ftrace.[instance.INSTANCE.]alloc_snapshot | |
76 | Allocate snapshot buffer. | |
77 | ||
78 | ftrace.[instance.INSTANCE.]cpumask = CPUMASK | |
79 | Set CPUMASK as trace cpu-mask. | |
80 | ||
81 | ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]] | |
82 | Enable given events on boot. You can use a wild card in EVENT. | |
83 | ||
84 | ftrace.[instance.INSTANCE.]tracer = TRACER | |
85 | Set TRACER to current tracer on boot. (e.g. function) | |
86 | ||
87 | ftrace.[instance.INSTANCE.]ftrace.filters | |
b8381ce7 | 88 | This will take an array of tracing function filter rules. |
47781947 MH |
89 | |
90 | ftrace.[instance.INSTANCE.]ftrace.notraces | |
b8381ce7 | 91 | This will take an array of NON-tracing function filter rules. |
47781947 MH |
92 | |
93 | ||
94 | Ftrace Per-Event Options | |
95 | ------------------------ | |
96 | ||
97 | These options are setting per-event options. | |
98 | ||
99 | ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable | |
b8381ce7 | 100 | Enable GROUP:EVENT tracing. |
47781947 MH |
101 | |
102 | ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER | |
103 | Set FILTER rule to the GROUP:EVENT. | |
104 | ||
105 | ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]] | |
106 | Set ACTIONs to the GROUP:EVENT. | |
107 | ||
108 | ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]] | |
109 | Defines new kprobe event based on PROBEs. It is able to define | |
110 | multiple probes on one event, but those must have same type of | |
111 | arguments. This option is available only for the event which | |
112 | group name is "kprobes". | |
113 | ||
114 | ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]] | |
115 | Defines new synthetic event with FIELDs. Each field should be | |
116 | "type varname". | |
117 | ||
118 | Note that kprobe and synthetic event definitions can be written under | |
119 | instance node, but those are also visible from other instances. So please | |
120 | take care for event name conflict. | |
121 | ||
122 | ||
123 | Examples | |
124 | ======== | |
125 | ||
126 | For example, to add filter and actions for each event, define kprobe | |
127 | events, and synthetic events with histogram, write a boot config like | |
128 | below:: | |
129 | ||
130 | ftrace.event { | |
131 | task.task_newtask { | |
132 | filter = "pid < 128" | |
133 | enable | |
134 | } | |
135 | kprobes.vfs_read { | |
136 | probes = "vfs_read $arg1 $arg2" | |
137 | filter = "common_pid < 200" | |
138 | enable | |
139 | } | |
140 | synthetic.initcall_latency { | |
141 | fields = "unsigned long func", "u64 lat" | |
142 | actions = "hist:keys=func.sym,lat:vals=lat:sort=lat" | |
143 | } | |
144 | initcall.initcall_start { | |
145 | actions = "hist:keys=func:ts0=common_timestamp.usecs" | |
146 | } | |
147 | initcall.initcall_finish { | |
148 | actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)" | |
149 | } | |
150 | } | |
151 | ||
b8381ce7 | 152 | Also, boot-time tracing supports "instance" node, which allows us to run |
47781947 | 153 | several tracers for different purpose at once. For example, one tracer |
b8381ce7 MH |
154 | is for tracing functions starting with "user\_", and others tracing |
155 | "kernel\_" functions, you can write boot config as below:: | |
47781947 MH |
156 | |
157 | ftrace.instance { | |
158 | foo { | |
159 | tracer = "function" | |
160 | ftrace.filters = "user_*" | |
161 | } | |
162 | bar { | |
163 | tracer = "function" | |
164 | ftrace.filters = "kernel_*" | |
165 | } | |
166 | } | |
167 | ||
168 | The instance node also accepts event nodes so that each instance | |
169 | can customize its event tracing. | |
170 | ||
171 | This boot-time tracing also supports ftrace kernel parameters via boot | |
172 | config. | |
173 | For example, following kernel parameters:: | |
174 | ||
175 | trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*" | |
176 | ||
177 | This can be written in boot config like below:: | |
178 | ||
179 | kernel { | |
180 | trace_options = sym-addr | |
181 | trace_event = "initcall:*" | |
182 | tp_printk | |
183 | trace_buf_size = 1M | |
184 | ftrace = function | |
185 | ftrace_filter = "vfs*" | |
186 | } | |
187 | ||
188 | Note that parameters start with "kernel" prefix instead of "ftrace". |