share/man/man4/boottrace.4

   1 .\" SPDX-License-Identifier: BSD-2-Clause
   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
  36 is a kernel-userspace interface for capturing trace events
  37 during system boot and shutdown
  38 .Pq in particular, one-shot events .
  39 .Pp
  40 Event annotations are present in:
  41 .Bl -bullet -compact
  42 .It
  43 the boot and shutdown paths in the
  44 kernel
  45 .It
  46 some 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
  54 scripts
  55 .El
  56 .Pp
  57 .Nm
  58 is unconditionally compiled into the kernel and
  59 disabled by default.
  60 .Sh EVENT TABLES
  61 Events are stored in three event tables: boot-time events, run-time events,
  62 and 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
  67 execution;
  68 .Xo
  69 until
  70 .Xr init 8
  71 transitions into multi-user mode
  72 .Xc
  73 .It run-time events Ta Xo
  74 From when the system has completed booting (including
  75 .Xr rc 8
  76 execution) and
  77 .Xr init 8
  78 transitions to multi-user mode
  79 until the beginning of shutdown procedures
  80 .Xc
  81 .It shutdown-time events Ta Xo
  82 After initialization of a shutdown, a reboot, or a kernel panic
  83 .Xc
  84 .El
  85 .Sh LOADER TUNABLES
  86 Tunables can be set at the
  87 .Xr loader 8
  88 prompt before booting the kernel or stored in
  89 .Xr loader.conf 5 .
  90 .Nm
  91 features the following loader tunables:
  92 .Bl -tag -width indent
  93 .It Va kern.boottrace.dotrace_kernel
  94 Set to
  95 .Ql 1
  96 to enable tracing of kernel events.
  97 Default:
  98 .Ql 1
  99 .Pq enabled .
 100 .It Va kern.boottrace.dotrace_user
 101 Set to
 102 .Ql 1
 103 to enable tracing of userspace events.
 104 Default:
 105 .Ql 1
 106 .Pq enabled .
 107 .El
 108 .Sh SYSCTL VARIABLES
 109 The following variables are available as both
 110 .Xr sysctl 8
 111 variables and
 112 .Xr loader 8
 113 tunables:
 114 .Bl -tag -width indent
 115 .It Va kern.boottrace.boottrace
 116 Create a new trace event and write it to the boot-time table.
 117 .Pp
 118 A new trace event consists of a process name and an event description,
 119 separated by a colon
 120 .Pq Ql \&: .
 121 If the colon is missing or if the provided string for the process name is empty,
 122 the process name is inferred from the invoking process
 123 .Pq which is its executable name .
 124 .It Va kern.boottrace.enabled
 125 Set to
 126 .Ql 1
 127 to enable tracing.
 128 This is a read-only
 129 .Xr sysctl 8
 130 variable.
 131 Default:
 132 .Ql 0
 133 .Pq disabled .
 134 .It Va kern.boottrace.log
 135 Show the events stored in boot-time and run-time
 136 tables.
 137 This
 138 is an opaque
 139 .Xr sysctl 8
 140 variable.
 141 .It Va kern.boottrace.runtrace
 142 Same as
 143 .Va kern.boottrace.boottrace ,
 144 but write to the run-time table.
 145 .It Va kern.boottrace.shuttrace
 146 Same as
 147 .Va kern.boottrace.boottrace ,
 148 but write to the shutdown-time table.
 149 .It Va kern.boottrace.shutdown_trace
 150 Log shutdown-time events to the console before the system halts.
 151 .It Va kern.boottrace.shutdown_trace_threshold
 152 Set a time threshold for logging shutdown-time events in milliseconds.
 153 An event is ignored
 154 if the time difference to the previous event is less than
 155 the threshold value.
 156 Default:
 157 .Ql 0
 158 .Pq logs all events .
 159 .El
 160 .Sh EXAMPLES
 161 Create a new trace event with a process name
 162 .Dq foo
 163 and an event description
 164 .Dq bar
 165 using
 166 .Xr sysctl 8 :
 167 .Bd -literal -offset indent
 168 sysctl kern.boottrace.boottrace="foo:bar"
 169 .Ed
 170 .Pp
 171 Here is a sample output of
 172 .Va kern.boottrace.log
 173 .Po shortened with
 174 .Dq [...]
 175 for readability
 176 .Pc :
 177 .Bd -literal
 178 CPU      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
 200 Total measured time: 10068 msecs
 201
 202
 203 CPU      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
 206 Total 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
 213 NetApp created
 214 .Nm
 215 to diagnose slow devices and subsystems.
 216 Once upstreamed,
 217 .Nm
 218 was first publicly released with
 219 .Fx 14.0 .
 220 .Sh AUTHORS
 221 This manual page was written by
 222 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .