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 March 4, 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.Pp 39Event annotations are present in: 40.Bl -bullet -compact 41.It 42the boot and shutdown paths in the 43kernel 44.It 45some key system utilities 46.Po 47.Xr init 8 , 48.Xr shutdown 8 , 49.Xr reboot 8 50.Pc 51.It 52.Xr rc 8 53scripts 54.El 55.Pp 56.Nm 57is unconditionally compiled into the kernel and 58disabled by default. 59.Sh EVENT TABLES 60Events are stored in three event tables: boot-time events, run-time events, 61and shutdown-time events. 62.Bl -column "shutdown-time events" "" 63.It Sy Table Name Ta Sy Event Description 64.It boot-time events Ta Boot, kernel initialization, and 65.Xr rc 8 66execution; 67.Xo 68until 69.Xr init 8 70transitions into multi-user mode 71.Xc 72.It run-time events Ta Xo 73From when the system has completed booting (including 74.Xr rc 8 75execution) and 76.Xr init 8 77transitions to multi-user mode 78until the beginning of shutdown procedures 79.Xc 80.It shutdown-time events Ta Xo 81After initialization of a shutdown, a reboot, or a kernel panic 82.Xc 83.El 84.Sh LOADER TUNABLES 85Tunables can be set at the 86.Xr loader 8 87prompt before booting the kernel or stored in 88.Xr loader.conf 5 . 89.Nm 90features the following loader tunables: 91.Bl -tag -width indent 92.It Va kern.boottrace.dotrace_kernel 93Set to 94.Ql 1 95to enable tracing of kernel events. 96Default: 97.Ql 1 98.Pq enabled . 99.It Va kern.boottrace.dotrace_user 100Set to 101.Ql 1 102to enable tracing of userspace events. 103Default: 104.Ql 1 105.Pq enabled . 106.El 107.Sh SYSCTL VARIABLES 108The following variables are available as both 109.Xr sysctl 8 110variables and 111.Xr loader 8 112tunables: 113.Bl -tag -width indent 114.It Va kern.boottrace.boottrace 115Create a new trace event and write it to the boot-time table. 116.Pp 117A new trace event consists of a process name and an event description, 118separated by a colon 119.Pq Ql \&: . 120If the colon is missing or if the provided string for the process name is empty, 121the process name is inferred from the invoking process 122.Pq which is its executable name . 123.It Va kern.boottrace.enabled 124Set to 125.Ql 1 126to enable tracing. 127This is a read-only 128.Xr sysctl 8 129variable. 130Default: 131.Ql 0 132.Pq disabled . 133.It Va kern.boottrace.log 134Show the events stored in boot-time and run-time 135tables. 136This 137is an opaque 138.Xr sysctl 8 139variable. 140.It Va kern.boottrace.runtrace 141Same as 142.Va kern.boottrace.boottrace , 143but write to the run-time table. 144.It Va kern.boottrace.shuttrace 145Same as 146.Va kern.boottrace.boottrace , 147but write to the shutdown-time table. 148.It Va kern.boottrace.shutdown_trace 149Log shutdown-time events to the console before the system halts. 150.It Va kern.boottrace.shutdown_trace_threshold 151Set a time threshold for logging shutdown-time events in milliseconds. 152An event is ignored 153if the time difference to the previous event is less than 154the threshold value. 155Default: 156.Ql 0 157.Pq logs all events . 158.El 159.Sh EXAMPLES 160Create a new trace event with a process name 161.Dq foo 162and an event description 163.Dq bar 164using 165.Xr sysctl 8 : 166.Bd -literal -offset indent 167sysctl kern.boottrace.boottrace="foo:bar" 168.Ed 169.Pp 170Here is a sample output of 171.Va kern.boottrace.log 172.Po shortened with 173.Dq [...] 174for readability 175.Pc : 176.Bd -literal 177CPU msecs delta process event PID CPUtime IBlks OBlks 178 0 44872811 0 kernel sysinit 0x2100001 0 0.00 0 0 179 0 44872812 1 kernel sysinit 0x2110000 0 0.00 0 0 180 0 44872812 0 kernel sysinit 0x2140000 0 0.00 0 0 181[...] 182 0 44872817 0 kernel sysinit 0x2800000 0 0.00 0 0 183 0 44873820 1003 kernel sysinit 0x2880000 0 0.00 0 0 184 0 44873820 0 kernel sysinit 0x2888000 0 0.00 0 0 185[...] 186 1 44875735 0 kernel sysinit 0xfffffff 0 0.00 0 0 187 1 44875735 0 swapper mi_startup done 0 0.00 0 0 188 0 44875750 15 init init(8) starting... 1 0.00 0 0 189 0 44875751 1 init /etc/rc starting... 1 0.00 0 0 190 0 44875831 80 boottrace /etc/rc.d/rctl start 26 0.00 0 0 191 1 44875839 8 boottrace /etc/rc.d/rctl done 26 0.00 2 0 192[...] 193 0 44876446 0 boottrace /etc/rc.d/netif start 390 0.00 0 0 194 1 44881116 4670 boottrace /etc/rc.d/netif done 390 0.12 34 0 195[...] 196 0 44882866 1 boottrace /etc/rc.d/securelevel start 1679 0.00 0 0 197 0 44882872 6 boottrace /etc/rc.d/securelevel done 1679 0.00 0 0 198 1 44882879 7 init /etc/rc finished 1 2.22 743 15 199Total measured time: 10068 msecs 200 201 202CPU msecs delta process event PID CPUtime IBlks OBlks 203 1 44882880 0 init multi-user start 1 2.22 743 15 204 0 44918215 35335 kldload hwpmc.ko: sysinit 0xd800000 1698 0.00 0 0 205Total measured time: 35335 msecs 206.Ed 207.Sh SEE ALSO 208.Xr tslog 4 , 209.Xr boottrace 8 , 210.Xr sysctl 8 211.Sh HISTORY 212NetApp created 213.Nm 214to diagnose slow devices and subsystems. 215Once upstreamed, 216.Nm 217was first publicly released with 218.Fx 14.0 . 219.Sh AUTHORS 220This manual page was written by 221.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 222