1.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 2.\" 3.\" Copyright (c) 2022 NetApp, Inc. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 1, 2022 27.Dt BOOTTRACE 4 28.Os 29.Sh NAME 30.Nm boottrace 31.Nd Boot-time, run-time, and shutdown-time tracing facility 32.Sh SYNOPSIS 33.In sys/boottrace.h 34.Sh DESCRIPTION 35.Nm 36is a kernel-userspace interface for capturing trace events 37during system boot and shutdown 38.Pq in particular, one-shot events . 39.Pp 40Event annotations are present in: 41.Bl -bullet -compact 42.It 43the boot and shutdown paths in the 44kernel 45.It 46some key system utilities 47.Po 48.Xr init 8 , 49.Xr shutdown 8 , 50.Xr reboot 8 51.Pc 52.It 53.Xr rc 8 54scripts 55.El 56.Pp 57.Nm 58is unconditionally compiled into the kernel and 59disabled by default. 60.Sh EVENT TABLES 61Events are stored in three event tables: boot-time events, run-time events, 62and shutdown-time events. 63.Bl -column "shutdown-time events" "" 64.It Sy Table Name Ta Sy Event Description 65.It boot-time events Ta Boot, kernel initialization, and 66.Xr rc 8 67execution; 68.Xo 69until 70.Xr init 8 71transitions into multi-user mode 72.Xc 73.It run-time events Ta Xo 74From when the system has completed booting (including 75.Xr rc 8 76execution) and 77.Xr init 8 78transitions to multi-user mode 79until the beginning of shutdown procedures 80.Xc 81.It shutdown-time events Ta Xo 82After initialization of a shutdown, a reboot, or a kernel panic 83.Xc 84.El 85.Sh LOADER TUNABLES 86Tunables can be set at the 87.Xr loader 8 88prompt before booting the kernel or stored in 89.Xr loader.conf 5 . 90.Nm 91features the following loader tunables: 92.Bl -tag -width indent 93.It Va kern.boottrace.dotrace_kernel 94Set to 95.Ql 1 96to enable tracing of kernel events. 97Default: 98.Ql 1 99.Pq enabled . 100.It Va kern.boottrace.dotrace_user 101Set to 102.Ql 1 103to enable tracing of userspace events. 104Default: 105.Ql 1 106.Pq enabled . 107.El 108.Sh SYSCTL VARIABLES 109The following variables are available as both 110.Xr sysctl 8 111variables and 112.Xr loader 8 113tunables: 114.Bl -tag -width indent 115.It Va kern.boottrace.boottrace 116Create a new trace event and write it to the boot-time table. 117.Pp 118A new trace event consists of a process name and an event description, 119separated by a colon 120.Pq Ql \&: . 121If the colon is missing or if the provided string for the process name is empty, 122the process name is inferred from the invoking process 123.Pq which is its executable name . 124.It Va kern.boottrace.enabled 125Set to 126.Ql 1 127to enable tracing. 128This is a read-only 129.Xr sysctl 8 130variable. 131Default: 132.Ql 0 133.Pq disabled . 134.It Va kern.boottrace.log 135Show the events stored in boot-time and run-time 136tables. 137This 138is an opaque 139.Xr sysctl 8 140variable. 141.It Va kern.boottrace.runtrace 142Same as 143.Va kern.boottrace.boottrace , 144but write to the run-time table. 145.It Va kern.boottrace.shuttrace 146Same as 147.Va kern.boottrace.boottrace , 148but write to the shutdown-time table. 149.It Va kern.boottrace.shutdown_trace 150Log shutdown-time events to the console before the system halts. 151.It Va kern.boottrace.shutdown_trace_threshold 152Set a time threshold for logging shutdown-time events in milliseconds. 153An event is ignored 154if the time difference to the previous event is less than 155the threshold value. 156Default: 157.Ql 0 158.Pq logs all events . 159.El 160.Sh EXAMPLES 161Create a new trace event with a process name 162.Dq foo 163and an event description 164.Dq bar 165using 166.Xr sysctl 8 : 167.Bd -literal -offset indent 168sysctl kern.boottrace.boottrace="foo:bar" 169.Ed 170.Pp 171Here is a sample output of 172.Va kern.boottrace.log 173.Po shortened with 174.Dq [...] 175for readability 176.Pc : 177.Bd -literal 178CPU msecs delta process event PID CPUtime IBlks OBlks 179 0 44872811 0 kernel sysinit 0x2100001 0 0.00 0 0 180 0 44872812 1 kernel sysinit 0x2110000 0 0.00 0 0 181 0 44872812 0 kernel sysinit 0x2140000 0 0.00 0 0 182[...] 183 0 44872817 0 kernel sysinit 0x2800000 0 0.00 0 0 184 0 44873820 1003 kernel sysinit 0x2880000 0 0.00 0 0 185 0 44873820 0 kernel sysinit 0x2888000 0 0.00 0 0 186[...] 187 1 44875735 0 kernel sysinit 0xfffffff 0 0.00 0 0 188 1 44875735 0 swapper mi_startup done 0 0.00 0 0 189 0 44875750 15 init init(8) starting... 1 0.00 0 0 190 0 44875751 1 init /etc/rc starting... 1 0.00 0 0 191 0 44875831 80 boottrace /etc/rc.d/rctl start 26 0.00 0 0 192 1 44875839 8 boottrace /etc/rc.d/rctl done 26 0.00 2 0 193[...] 194 0 44876446 0 boottrace /etc/rc.d/netif start 390 0.00 0 0 195 1 44881116 4670 boottrace /etc/rc.d/netif done 390 0.12 34 0 196[...] 197 0 44882866 1 boottrace /etc/rc.d/securelevel start 1679 0.00 0 0 198 0 44882872 6 boottrace /etc/rc.d/securelevel done 1679 0.00 0 0 199 1 44882879 7 init /etc/rc finished 1 2.22 743 15 200Total measured time: 10068 msecs 201 202 203CPU msecs delta process event PID CPUtime IBlks OBlks 204 1 44882880 0 init multi-user start 1 2.22 743 15 205 0 44918215 35335 kldload hwpmc.ko: sysinit 0xd800000 1698 0.00 0 0 206Total measured time: 35335 msecs 207.Ed 208.Sh SEE ALSO 209.Xr tslog 4 , 210.Xr boottrace 8 , 211.Xr sysctl 8 212.Sh HISTORY 213NetApp created 214.Nm 215to diagnose slow devices and subsystems. 216Once upstreamed, 217.Nm 218was first publicly released with 219.Fx 14.0 . 220.Sh AUTHORS 221This manual page was written by 222.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 223