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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2022 NetApp, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd July 1, 2022
.Dt BOOTTRACE 4
.Os
.Sh NAME
.Nm boottrace
.Nd Boot-time, run-time, and shutdown-time tracing facility
.Sh SYNOPSIS
.In sys/boottrace.h
.Sh DESCRIPTION
.Nm
is a kernel-userspace interface for capturing trace events
during system boot and shutdown
.Pq in particular, one-shot events .
.Pp
Event annotations are present in:
.Bl -bullet -compact
.It
the boot and shutdown paths in the
kernel
.It
some key system utilities
.Po
.Xr init 8 ,
.Xr shutdown 8 ,
.Xr reboot 8
.Pc
.It
.Xr rc 8
scripts
.El
.Pp
.Nm
is unconditionally compiled into the kernel and
disabled by default.
.Sh EVENT TABLES
Events are stored in three event tables: boot-time events, run-time events,
and shutdown-time events.
.Bl -column "shutdown-time events" ""
.It Sy Table Name Ta Sy Event Description
.It boot-time events Ta Boot, kernel initialization, and
.Xr rc 8
execution;
.Xo
until
.Xr init 8
transitions into multi-user mode
.Xc
.It run-time events Ta Xo
From when the system has completed booting (including
.Xr rc 8
execution) and
.Xr init 8
transitions to multi-user mode
until the beginning of shutdown procedures
.Xc
.It shutdown-time events Ta Xo
After initialization of a shutdown, a reboot, or a kernel panic
.Xc
.El
.Sh LOADER TUNABLES
Tunables can be set at the
.Xr loader 8
prompt before booting the kernel or stored in
.Xr loader.conf 5 .
.Nm
features the following loader tunables:
.Bl -tag -width indent
.It Va kern.boottrace.dotrace_kernel
Set to
.Ql 1
to enable tracing of kernel events.
Default:
.Ql 1
.Pq enabled .
.It Va kern.boottrace.dotrace_user
Set to
.Ql 1
to enable tracing of userspace events.
Default:
.Ql 1
.Pq enabled .
.El
.Sh SYSCTL VARIABLES
The following variables are available as both
.Xr sysctl 8
variables and
.Xr loader 8
tunables:
.Bl -tag -width indent
.It Va kern.boottrace.boottrace
Create a new trace event and write it to the boot-time table.
.Pp
A new trace event consists of a process name and an event description,
separated by a colon
.Pq Ql \&: .
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
.Pq which is its executable name .
.It Va kern.boottrace.enabled
Set to
.Ql 1
to enable tracing.
This is a read-only
.Xr sysctl 8
variable.
Default:
.Ql 0
.Pq disabled .
.It Va kern.boottrace.log
Show the events stored in boot-time and run-time
tables.
This
is an opaque
.Xr sysctl 8
variable.
.It Va kern.boottrace.runtrace
Same as
.Va kern.boottrace.boottrace ,
but write to the run-time table.
.It Va kern.boottrace.shuttrace
Same as
.Va kern.boottrace.boottrace ,
but write to the shutdown-time table.
.It Va kern.boottrace.shutdown_trace
Log shutdown-time events to the console before the system halts.
.It Va kern.boottrace.shutdown_trace_threshold
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:
.Ql 0
.Pq logs all events .
.El
.Sh EXAMPLES
Create a new trace event with a process name
.Dq foo
and an event description
.Dq bar
using
.Xr sysctl 8 :
.Bd -literal -offset indent
sysctl kern.boottrace.boottrace="foo:bar"
.Ed
.Pp
Here is a sample output of
.Va kern.boottrace.log
.Po shortened with
.Dq [...]
for readability
.Pc :
.Bd -literal
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
.Ed
.Sh SEE ALSO
.Xr tslog 4 ,
.Xr boottrace 8 ,
.Xr sysctl 8
.Sh HISTORY
NetApp created
.Nm
to diagnose slow devices and subsystems.
Once upstreamed,
.Nm
was first publicly released with
.Fx 14.0 .
.Sh AUTHORS
This manual page was written by
.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
|
