diff options
author | Mateusz Piotrowski <0mp@FreeBSD.org> | 2022-02-28 21:51:03 +0000 |
---|---|---|
committer | Mateusz Piotrowski <0mp@FreeBSD.org> | 2022-02-28 21:51:40 +0000 |
commit | 1ae2c59bcf21686036ecc23df3f1a8e15d57d074 (patch) | |
tree | d9ddc20a7cbdc79716548c1f56f5d978b8156982 | |
parent | 9291d079d54b828b43d3714a5f19f0ffe92837b8 (diff) | |
download | src-1ae2c59bcf21.tar.gz src-1ae2c59bcf21.zip |
Add a manual page for boottrace(4)
Reviewed by: mhorne, pauamma_gundo.com
Sponsored by: NetApp, Inc.
Sponsored by: Klara, Inc
Differential Revision: https://reviews.freebsd.org/D33275
-rw-r--r-- | share/man/man4/Makefile | 1 | ||||
-rw-r--r-- | share/man/man4/boottrace.4 | 220 |
2 files changed, 221 insertions, 0 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 23582e95c79b..c79fc1de0c76 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -81,6 +81,7 @@ MAN= aac.4 \ bhndb_pci.4 \ blackhole.4 \ bnxt.4 \ + boottrace.4 \ bpf.4 \ bridge.4 \ bwi.4 \ diff --git a/share/man/man4/boottrace.4 b/share/man/man4/boottrace.4 new file mode 100644 index 000000000000..41c37df741fb --- /dev/null +++ b/share/man/man4/boottrace.4 @@ -0,0 +1,220 @@ +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" +.\" 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 February 28, 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. +.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 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 . |