From nobody Mon Feb 28 21:52:36 2022 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id B772319D92A1; Mon, 28 Feb 2022 21:52:36 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4K6vHm4kg5z3FMV; Mon, 28 Feb 2022 21:52:36 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1646085156; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bov2fAu4r404iQsbbSaeaggGuKtHflgT1QrkGLvidRQ=; b=FJvucDJ/JSHj3dq+5qfHLWxIvFdqEZSewKncOsKlTDvAWw7H0PtT8tzESLanueGeAoG+GL HXUxC9qDgliBtGtLhVLDucZ+4ewYJQ0LEXlCr7A8/FqFaq8B8DjkvpCcU5nDq4OBW2EgT5 owEPpsCJORS5WNfBw51sihzsCP5fX2fJ5oaOrhXhY01kECGk2CvJHnZ1xwpG2vrT4u9KZG pskF/VhprnIcw2v4uud4wyGnsH8xbFlB4V3e8EeZYmz6ILeGERvNkrEWqPdZx5WisMApCd /Bc2aJ4bcJctNSSvRXwGArRRZaPSlYg9z4GRXe20uBiqhgQjQvJba8Bogu2HbA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 8243C232D2; Mon, 28 Feb 2022 21:52:36 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 21SLqad8095855; Mon, 28 Feb 2022 21:52:36 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 21SLqacB095854; Mon, 28 Feb 2022 21:52:36 GMT (envelope-from git) Date: Mon, 28 Feb 2022 21:52:36 GMT Message-Id: <202202282152.21SLqacB095854@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: 1ae2c59bcf21 - main - Add a manual page for boottrace(4) List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: 0mp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 1ae2c59bcf21686036ecc23df3f1a8e15d57d074 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1646085156; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bov2fAu4r404iQsbbSaeaggGuKtHflgT1QrkGLvidRQ=; b=tLDfVAFhBJfl5FJBMclTRlolFKvEHmjXm1N1GJPqAGSTz6bOhu9rOH1B5Cbps8bBFSKigG cf1XILS7jdUm9C5NZVb5ywtb+U2okVdLZwLZbCeln0uXf7GH11eUkqGCX3gFxYcICnE6/T PI+h7d4xdIxyrGP8NwuHTTUdJ5GiRgvHSff7FeijHIsQwtA0jTuLJb7O3+w/0D0xwmpvee /DGjaif0HEJmfWyI9G5vy++OLEKF6/gRd2XhprQVI9mS/YFWNwbSd10NGP4Js2sfmoGEnk NqvCxKmW7J5pJZDFH2C4IFeHSkA3h2ya8AAiaUpabe5nz81XRiSA/6ZViePvTQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1646085156; a=rsa-sha256; cv=none; b=KhQSKhN47G+oVwikq4AJsw6xzL5dfPhMUSrbtkC+QN5lLUhTIj0TxEOt3ZVc3W+Br3eyqA ZHwYYfVBQDErUdPz/OVNpIcd0UlWfeV3nfa/QqrQO4FXXAY7zTSQFQdGW6VR3kHmwMDn9V JBC3oUFHDL3tG/Ft1DFw9vbNYuJzEsQTAXDCWpHVn+Wm9uEb9aSsz9wvrcPlGTfpX3jYcW L7xf6lmKJkgnMJsVcyvwwfJEK7Xn5zCvupckQhqgmwIgESIVpf7ZP3LwBNYczoRvReb20x ftIv0dklg2od9comm+Cc5l0oICNy3+dcP5IrazYBMdP3ocV9Hw2rgKZzQmMnCA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by 0mp (doc, ports committer): URL: https://cgit.FreeBSD.org/src/commit/?id=1ae2c59bcf21686036ecc23df3f1a8e15d57d074 commit 1ae2c59bcf21686036ecc23df3f1a8e15d57d074 Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2022-02-28 21:51:03 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2022-02-28 21:51:40 +0000 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 --- share/man/man4/Makefile | 1 + share/man/man4/boottrace.4 | 220 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) 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 .