1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd June 19, 2025 7.Dt TRACING 7 8.Os 9.Sh NAME 10.Nm tracing 11.Nd introduction to tracing and performance monitoring facilities 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.Pp 38.Ss Userland Tracing 39.Xr truss 1 40traces system calls. 41It uses 42.Xr sysdecode 3 43to pretty-print system call arguments and 44.Xr ptrace 2 45to trace processes. 46.Pp 47.Xr ktrace 1 48is useful for debugging user programs. 49It enables kernel trace logging for specified processes. 50Like 51.Xr truss 1 , 52it mainly traces system calls, but instead of using 53.Xr ptrace 2 , 54it asynchronously logs entries to a trace file configured with 55.Xr ktrace 2 56(typically 57.Pa ktrace.out ) , 58and it can log other types of kernel events, such as page faults and 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 Counters 77.Pp 78.Xr pmcstat 8 , 79and its kernel counterpart, 80.Xr hwmpc 4 , 81is the 82.Fx 83facility for conducting performance measurements with hardware counters. 84.Ss Boot-Time And Shutdown Tracing 85.Xr boottrace 4 86is a facility for tracing events at boot and shutdown. 87Its target audience are system administrators. 88.Pp 89.Xr tslog 4 90is a developer-oriented tool for tracing boot-time events. 91.Sh HISTORY 92The 93.Nm 94manual page was written by 95.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 96It first appeared in 97.Fx 15.0 . 98