1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
<table class="head">
<tr>
<td class="head-ltitle">BOOTTRACE(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">BOOTTRACE(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">boottrace</code> —
<span class="Nd">Boot-time, run-time, and shutdown-time tracing
facility</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/boottrace.h</a>></code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><code class="Nm">boottrace</code> is a kernel-userspace interface
for capturing trace events during system boot and shutdown (in particular,
one-shot events).</p>
<p class="Pp">Event annotations are present in:</p>
<ul class="Bl-bullet Bl-compact">
<li>the boot and shutdown paths in the kernel</li>
<li>some key system utilities (<a class="Xr">init(8)</a>,
<a class="Xr">shutdown(8)</a>, <a class="Xr">reboot(8)</a>)</li>
<li><a class="Xr">rc(8)</a> scripts</li>
</ul>
<p class="Pp"><code class="Nm">boottrace</code> is unconditionally compiled into
the kernel and disabled by default.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EVENT_TABLES"><a class="permalink" href="#EVENT_TABLES">EVENT
TABLES</a></h1>
<p class="Pp">Events are stored in three event tables: boot-time events,
run-time events, and shutdown-time events.</p>
<table class="Bl-column">
<tr id="Table">
<td><a class="permalink" href="#Table"><b class="Sy">Table Name</b></a></td>
<td><a class="permalink" href="#Event"><b class="Sy" id="Event">Event
Description</b></a></td>
</tr>
<tr>
<td>boot-time events</td>
<td>Boot, kernel initialization, and <a class="Xr">rc(8)</a> execution;
until <a class="Xr">init(8)</a> transitions into multi-user mode</td>
</tr>
<tr>
<td>run-time events</td>
<td>From when the system has completed booting (including
<a class="Xr">rc(8)</a> execution) and <a class="Xr">init(8)</a>
transitions to multi-user mode until the beginning of shutdown
procedures</td>
</tr>
<tr>
<td>shutdown-time events</td>
<td>After initialization of a shutdown, a reboot, or a kernel panic</td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="LOADER_TUNABLES"><a class="permalink" href="#LOADER_TUNABLES">LOADER
TUNABLES</a></h1>
<p class="Pp">Tunables can be set at the <a class="Xr">loader(8)</a> prompt
before booting the kernel or stored in <a class="Xr">loader.conf(5)</a>.
<code class="Nm">boottrace</code> features the following loader
tunables:</p>
<dl class="Bl-tag">
<dt id="kern.boottrace.dotrace_kernel"><var class="Va">kern.boottrace.dotrace_kernel</var></dt>
<dd>Set to ‘<code class="Li">1</code>’ to enable tracing of
kernel events. Default: ‘<code class="Li">1</code>’
(enabled).</dd>
<dt id="kern.boottrace.dotrace_user"><var class="Va">kern.boottrace.dotrace_user</var></dt>
<dd>Set to ‘<code class="Li">1</code>’ to enable tracing of
userspace events. Default: ‘<code class="Li">1</code>’
(enabled).</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SYSCTL_VARIABLES"><a class="permalink" href="#SYSCTL_VARIABLES">SYSCTL
VARIABLES</a></h1>
<p class="Pp">The following variables are available as both
<a class="Xr">sysctl(8)</a> variables and <a class="Xr">loader(8)</a>
tunables:</p>
<dl class="Bl-tag">
<dt id="kern.boottrace.boottrace"><var class="Va">kern.boottrace.boottrace</var></dt>
<dd>Create a new trace event and write it to the boot-time table.
<p class="Pp">A new trace event consists of a process name and an event
description, separated by a colon
(‘<code class="Li">:</code>’). If the colon is missing or
if the provided string for the process name is empty, the process name
is inferred from the invoking process (which is its executable
name).</p>
</dd>
<dt id="kern.boottrace.enabled"><var class="Va">kern.boottrace.enabled</var></dt>
<dd>Set to ‘<code class="Li">1</code>’ to enable tracing. This
is a read-only <a class="Xr">sysctl(8)</a> variable. Default:
‘<code class="Li">0</code>’ (disabled).</dd>
<dt id="kern.boottrace.log"><var class="Va">kern.boottrace.log</var></dt>
<dd>Show the events stored in boot-time and run-time tables. This is an opaque
<a class="Xr">sysctl(8)</a> variable.</dd>
<dt id="kern.boottrace.runtrace"><var class="Va">kern.boottrace.runtrace</var></dt>
<dd>Same as <var class="Va">kern.boottrace.boottrace</var>, but write to the
run-time table.</dd>
<dt id="kern.boottrace.shuttrace"><var class="Va">kern.boottrace.shuttrace</var></dt>
<dd>Same as <var class="Va">kern.boottrace.boottrace</var>, but write to the
shutdown-time table.</dd>
<dt id="kern.boottrace.shutdown_trace"><var class="Va">kern.boottrace.shutdown_trace</var></dt>
<dd>Log shutdown-time events to the console before the system halts.</dd>
<dt id="kern.boottrace.shutdown_trace_threshold"><var class="Va">kern.boottrace.shutdown_trace_threshold</var></dt>
<dd>Set a time threshold for logging shutdown-time events in milliseconds. An
event is ignored if the time difference to the previous event is less than
the threshold value. Default: ‘<code class="Li">0</code>’
(logs all events).</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">Create a new trace event with a process name “foo”
and an event description “bar” using
<a class="Xr">sysctl(8)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>sysctl kern.boottrace.boottrace="foo:bar"</pre>
</div>
<p class="Pp">Here is a sample output of
<var class="Va">kern.boottrace.log</var> (shortened with
“[...]” for readability):</p>
<div class="Bd Pp Li">
<pre>CPU msecs delta process event PID CPUtime IBlks OBlks
0 44872811 0 kernel sysinit 0x2100001 0 0.00 0 0
0 44872812 1 kernel sysinit 0x2110000 0 0.00 0 0
0 44872812 0 kernel sysinit 0x2140000 0 0.00 0 0
[...]
0 44872817 0 kernel sysinit 0x2800000 0 0.00 0 0
0 44873820 1003 kernel sysinit 0x2880000 0 0.00 0 0
0 44873820 0 kernel sysinit 0x2888000 0 0.00 0 0
[...]
1 44875735 0 kernel sysinit 0xfffffff 0 0.00 0 0
1 44875735 0 swapper mi_startup done 0 0.00 0 0
0 44875750 15 init init(8) starting... 1 0.00 0 0
0 44875751 1 init /etc/rc starting... 1 0.00 0 0
0 44875831 80 boottrace /etc/rc.d/rctl start 26 0.00 0 0
1 44875839 8 boottrace /etc/rc.d/rctl done 26 0.00 2 0
[...]
0 44876446 0 boottrace /etc/rc.d/netif start 390 0.00 0 0
1 44881116 4670 boottrace /etc/rc.d/netif done 390 0.12 34 0
[...]
0 44882866 1 boottrace /etc/rc.d/securelevel start 1679 0.00 0 0
0 44882872 6 boottrace /etc/rc.d/securelevel done 1679 0.00 0 0
1 44882879 7 init /etc/rc finished 1 2.22 743 15
Total measured time: 10068 msecs
CPU msecs delta process event PID CPUtime IBlks OBlks
1 44882880 0 init multi-user start 1 2.22 743 15
0 44918215 35335 kldload hwpmc.ko: sysinit 0xd800000 1698 0.00 0 0
Total measured time: 35335 msecs</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">tslog(4)</a>, <a class="Xr">boottrace(8)</a>,
<a class="Xr">sysctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">NetApp created <code class="Nm">boottrace</code> to diagnose slow
devices and subsystems. Once upstreamed, <code class="Nm">boottrace</code>
was first publicly released with <span class="Ux">FreeBSD 14.0</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was written by <span class="An">Mateusz
Piotrowski</span>
<<a class="Mt" href="mailto:0mp@FreeBSD.org">0mp@FreeBSD.org</a>>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">July 1, 2022</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
