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 | ||
64 | ftrace.[instance.INSTANCE.]trace_clock = CLOCK | |
65 | Set given CLOCK to ftrace's trace_clock. | |
66 | ||
67 | ftrace.[instance.INSTANCE.]buffer_size = SIZE | |
68 | Configure ftrace buffer size to SIZE. You can use "KB" or "MB" | |
69 | for that SIZE. | |
70 | ||
71 | ftrace.[instance.INSTANCE.]alloc_snapshot | |
72 | Allocate snapshot buffer. | |
73 | ||
74 | ftrace.[instance.INSTANCE.]cpumask = CPUMASK | |
75 | Set CPUMASK as trace cpu-mask. | |
76 | ||
77 | ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]] | |
78 | Enable given events on boot. You can use a wild card in EVENT. | |
79 | ||
80 | ftrace.[instance.INSTANCE.]tracer = TRACER | |
81 | Set TRACER to current tracer on boot. (e.g. function) | |
82 | ||
83 | ftrace.[instance.INSTANCE.]ftrace.filters | |
b8381ce7 | 84 | This will take an array of tracing function filter rules. |
47781947 MH |
85 | |
86 | ftrace.[instance.INSTANCE.]ftrace.notraces | |
b8381ce7 | 87 | This will take an array of NON-tracing function filter rules. |
47781947 MH |
88 | |
89 | ||
90 | Ftrace Per-Event Options | |
91 | ------------------------ | |
92 | ||
93 | These options are setting per-event options. | |
94 | ||
95 | ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable | |
b8381ce7 | 96 | Enable GROUP:EVENT tracing. |
47781947 MH |
97 | |
98 | ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER | |
99 | Set FILTER rule to the GROUP:EVENT. | |
100 | ||
101 | ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]] | |
102 | Set ACTIONs to the GROUP:EVENT. | |
103 | ||
104 | ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]] | |
105 | Defines new kprobe event based on PROBEs. It is able to define | |
106 | multiple probes on one event, but those must have same type of | |
107 | arguments. This option is available only for the event which | |
108 | group name is "kprobes". | |
109 | ||
110 | ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]] | |
111 | Defines new synthetic event with FIELDs. Each field should be | |
112 | "type varname". | |
113 | ||
114 | Note that kprobe and synthetic event definitions can be written under | |
115 | instance node, but those are also visible from other instances. So please | |
116 | take care for event name conflict. | |
117 | ||
118 | ||
119 | Examples | |
120 | ======== | |
121 | ||
122 | For example, to add filter and actions for each event, define kprobe | |
123 | events, and synthetic events with histogram, write a boot config like | |
124 | below:: | |
125 | ||
126 | ftrace.event { | |
127 | task.task_newtask { | |
128 | filter = "pid < 128" | |
129 | enable | |
130 | } | |
131 | kprobes.vfs_read { | |
132 | probes = "vfs_read $arg1 $arg2" | |
133 | filter = "common_pid < 200" | |
134 | enable | |
135 | } | |
136 | synthetic.initcall_latency { | |
137 | fields = "unsigned long func", "u64 lat" | |
138 | actions = "hist:keys=func.sym,lat:vals=lat:sort=lat" | |
139 | } | |
140 | initcall.initcall_start { | |
141 | actions = "hist:keys=func:ts0=common_timestamp.usecs" | |
142 | } | |
143 | initcall.initcall_finish { | |
144 | actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)" | |
145 | } | |
146 | } | |
147 | ||
b8381ce7 | 148 | Also, boot-time tracing supports "instance" node, which allows us to run |
47781947 | 149 | several tracers for different purpose at once. For example, one tracer |
b8381ce7 MH |
150 | is for tracing functions starting with "user\_", and others tracing |
151 | "kernel\_" functions, you can write boot config as below:: | |
47781947 MH |
152 | |
153 | ftrace.instance { | |
154 | foo { | |
155 | tracer = "function" | |
156 | ftrace.filters = "user_*" | |
157 | } | |
158 | bar { | |
159 | tracer = "function" | |
160 | ftrace.filters = "kernel_*" | |
161 | } | |
162 | } | |
163 | ||
164 | The instance node also accepts event nodes so that each instance | |
165 | can customize its event tracing. | |
166 | ||
167 | This boot-time tracing also supports ftrace kernel parameters via boot | |
168 | config. | |
169 | For example, following kernel parameters:: | |
170 | ||
171 | trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*" | |
172 | ||
173 | This can be written in boot config like below:: | |
174 | ||
175 | kernel { | |
176 | trace_options = sym-addr | |
177 | trace_event = "initcall:*" | |
178 | tp_printk | |
179 | trace_buf_size = 1M | |
180 | ftrace = function | |
181 | ftrace_filter = "vfs*" | |
182 | } | |
183 | ||
184 | Note that parameters start with "kernel" prefix instead of "ftrace". |