1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd July 12, 2025 7.Dt TRACING 7 8.Os 9.Sh NAME 10.Nm tracing 11.Nd introduction to FreeBSD tracing and performance monitoring 12.Sh DESCRIPTION 13.Fx 14features a large variety of tracing and performance monitoring facilities. 15Use them to measure performance and 16troubleshoot kernel and userland problems both during 17.Xr development 7 18and potentially on production systems. 19The facilities differ in scope, ease of use, overhead, design, and limitations. 20.Ss DTrace 21.Xr dtrace 1 22is the most versatile tracing framework available on 23.Fx 24and is capable of tracing throughout the 25.Fx 26software stack from the kernel to the applications running in userland. 27Refer to 28.Xr dtrace 1 29and 30.Xr SDT 9 31for more details. 32.Pp 33.Xr dwatch 1 34is a user-friendly wrapper for DTrace. 35It simplifies common DTrace usage patterns and requires less expert knowledge 36to operate. 37.Ss Userland Tracing 38.Xr truss 1 39traces system calls. 40It uses 41.Xr sysdecode 3 42to pretty-print system call arguments and 43.Xr ptrace 2 44to trace processes. 45.Pp 46.Xr ktrace 1 47is useful for debugging user programs. 48It enables kernel trace logging for specified processes. 49Like 50.Xr truss 1 , 51it mainly traces system calls, but instead of using 52.Xr ptrace 2 , 53it asynchronously logs entries to a trace file configured with 54.Xr ktrace 2 55(typically 56.Pa ktrace.out ) , 57and it can log other types of kernel events, such as page faults 58and name lookups 59.Po refer to 60.Fl t 61in 62.Xr ktrace 1 63.Pc . 64Also, programs can log to a 65.Xr ktrace 1 66stream using the 67.Xr utrace 2 68system call. 69.Ss Kernel Tracing 70.Xr ktr 4 71is a facility for logging strings in the kernel. 72It comes in handy for some niche purposes during kernel development. 73It lets kernel programmers log events to a global ring buffer, 74which can later be dumped using 75.Xr ktrdump 8 . 76.Ss Hardware-Accelerated Tracing 77.Xr hwt 4 78is a kernel trace framework providing infrastructure 79for hardware-assisted tracing. 80.Ss Hardware Counters 81.Xr pmcstat 8 , 82and its kernel counterpart, 83.Xr hwpmc 4 , 84is the 85.Fx 86facility for conducting performance measurements with hardware counters. 87.Ss Boot-Time And Shutdown Tracing 88.Xr boottrace 4 89is a facility for tracing events at boot and shutdown. 90Its target audience are system administrators. 91.Pp 92.Xr tslog 4 93is a developer-oriented tool for tracing boot-time events. 94.Sh HISTORY 95The 96.Nm 97manual page was written by 98.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 99It first appeared in 100.Fx 15.0 . 101