---
name: "boottrace"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/boottrace/4"
---

# boottrace(4)

Boot-time, run-time, and shutdown-time tracing facility

## NAME

**boottrace** – Boot-time, run-time, and shutdown-time tracing facility

## SYNOPSIS

**#include \<sys/boottrace.h\>**

## DESCRIPTION

**boottrace** is a kernel-userspace interface for capturing trace events during system boot and shutdown (in particular, one-shot events).

Event annotations are present in:

- the boot and shutdown paths in the kernel

- some key system utilities( [init(8)](/init/8.md), [shutdown(8)](/shutdown/8.md), [reboot(8)](/reboot/8.md))

- [rc(8)](/rc/8.md) scripts

**boottrace** is unconditionally compiled into the kernel and disabled by default.

## EVENT TABLES

Events are stored in three event tables: boot-time events, run-time events, and shutdown-time events.

| | |
| --- | --- |
| **Table** **Name** | **Event** **Description** |
| boot-time events | Boot, kernel initialization, and |
| run-time events |  |
| shutdown-time events |  |

## LOADER TUNABLES

Tunables can be set at the [loader(8)](/loader/8.md) prompt before booting the kernel or stored in [loader.conf(5)](/loader.conf/5.md). **boottrace** features the following loader tunables:

- *kern.boottrace.dotrace\_kernel*

  Set to ‘1’ to enable tracing of kernel events. Default: ‘1’ (enabled).

- *kern.boottrace.dotrace\_user*

  Set to ‘1’ to enable tracing of userspace events. Default: ‘1’ (enabled).

## SYSCTL VARIABLES

The following variables are available as both [sysctl(8)](/sysctl/8.md) variables and [loader(8)](/loader/8.md) tunables:

- *kern.boottrace.boottrace*

  Create a new trace event and write it to the boot-time table.

  A new trace event consists of a process name and an event description, separated by a colon (‘:’). 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 (which is its executable name).

- *kern.boottrace.enabled*

  Set to ‘1’ to enable tracing. This is a read-only [sysctl(8)](/sysctl/8.md) variable. Default: ‘0’ (disabled).

- *kern.boottrace.log*

  Show the events stored in boot-time and run-time tables. This is an opaque [sysctl(8)](/sysctl/8.md) variable.

- *kern.boottrace.runtrace*

  Same as *kern.boottrace.boottrace*, but write to the run-time table.

- *kern.boottrace.shuttrace*

  Same as *kern.boottrace.boottrace*, but write to the shutdown-time table.

- *kern.boottrace.shutdown\_trace*

  Log shutdown-time events to the console before the system halts.

- *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: ‘0’ (logs all events).

## EXAMPLES

Create a new trace event with a process name “foo” and an event description “bar” using [sysctl(8)](/sysctl/8.md):

```
sysctl kern.boottrace.boottrace="foo:bar"
```

Here is a sample output of *kern.boottrace.log* (shortened with “\[...\]” for readability):

```
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
```

## SEE ALSO

[tslog(4)](/tslog/4.md), [boottrace(8)](/boottrace/8.md), [sysctl(8)](/sysctl/8.md)

## HISTORY

NetApp created **boottrace** to diagnose slow devices and subsystems. Once upstreamed, **boottrace** was first publicly released with FreeBSD 14.0.

## AUTHORS

This manual page was written by Mateusz Piotrowski ⟨*0mp@FreeBSD.org*⟩.