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