diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 2c4f158280f7..021bf9251bda 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -1,64 +1,65 @@ .include #MISSING: eqnchar.7 ms.7 term.7 MAN= arch.7 \ ascii.7 \ bsd.snmpmod.mk.7 \ build.7 \ c.7 \ clocks.7 \ crypto.7 \ development.7 \ environ.7 \ firewall.7 \ growfs.7 \ hier.7 \ hostname.7 \ intro.7 \ maclabel.7 \ mitigations.7 \ operator.7 \ orders.7 \ ports.7 \ release.7 \ sdoc.7 \ security.7 \ simd.7 \ sizeof.7 \ sprog.7 \ stats.7 \ stdint.7 \ sticky.7 \ tests.7 \ + tracing.7 \ tuning.7 MLINKS= intro.7 miscellaneous.7 MLINKS+= growfs.7 growfs_fstab.7 MLINKS+= security.7 securelevel.7 MLINKS+= c.7 c78.7 MLINKS+= c.7 c89.7 MLINKS+= c.7 c90.7 MLINKS+= c.7 c95.7 MLINKS+= c.7 c99.7 MLINKS+= c.7 c11.7 MLINKS+= c.7 c17.7 MLINKS+= c.7 c23.7 MLINKS+= c.7 c2y.7 .if ${MK_INET} != "no" MAN+= networking.7 MLINKS+= networking.7 wifi.7 .endif .if ${MK_TESTS} != "no" ATF= ${SRCTOP}/contrib/atf .PATH: ${ATF}/doc MAN+= atf.7 CLEANFILES+= atf.7 atf.7: atf.7.in sed -e 's,__DOCDIR__,/usr/share/doc/atf,g' \ <"${ATF}/doc/atf.7.in" >atf.7 .endif .include diff --git a/share/man/man7/tracing.7 b/share/man/man7/tracing.7 new file mode 100644 index 000000000000..0bd64f197084 --- /dev/null +++ b/share/man/man7/tracing.7 @@ -0,0 +1,97 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd June 19, 2025 +.Dt TRACING 7 +.Os +.Sh NAME +.Nm tracing +.Nd introduction to tracing and performance monitoring facilities +.Sh DESCRIPTION +.Fx +features a large variety of tracing and performance monitoring facilities. +Use them to measure performance and +troubleshoot kernel and userland problems both during +.Xr development 7 +and potentially on production systems. +The facilities differ in scope, ease of use, overhead, design, and limitations. +.Ss DTrace +.Xr dtrace 1 +is the most versatile tracing framework available on +.Fx +and is capable of tracing throughout the +.Fx +software stack from the kernel to the applications running in userland. +Refer to +.Xr dtrace 1 +and +.Xr SDT 9 +for more details. +.Pp +.Xr dwatch 1 +is a user-friendly wrapper for DTrace. +It simplifies common DTrace usage patterns and requires less expert knowledge +to operate. +.Pp +.Ss Userland Tracing +.Xr truss 1 +traces system calls. +It uses +.Xr sysdecode 3 +to pretty-print system call arguments and +.Xr ptrace 2 +to trace processes. +.Pp +.Xr ktrace 1 +is useful for debugging user programs. +It enables kernel trace logging for specified processes. +Like +.Xr truss 1 , +it mainly traces system calls, but instead of using +.Xr ptrace 2 , +it asynchronously logs entries to a trace file configured with +.Xr ktrace 2 +(typically +.Pa ktrace.out ) , +and it can log other types of kernel events, such as page faults and name lookups +.Po refer to +.Fl t +in +.Xr ktrace 1 +.Pc . +Also, programs can log to a +.Xr ktrace 1 +stream using the +.Xr utrace 2 +system call. +.Ss Kernel Tracing +.Xr ktr 4 +is a facility for logging strings in the kernel. +It comes in handy for some niche purposes during kernel development. +It lets kernel programmers log events to a global ring buffer, +which can later be dumped using +.Xr ktrdump 8 . +.Ss Hardware Counters +.Pp +.Xr pmcstat 8 , +and its kernel counterpart, +.Xr hwmpc 4 , +is the +.Fx +facility for conducting performance measurements with hardware counters. +.Ss Boot-Time And Shutdown Tracing +.Xr boottrace 4 +is a facility for tracing events at boot and shutdown. +Its target audience are system administrators. +.Pp +.Xr tslog 4 +is a developer-oriented tool for tracing boot-time events. +.Sh HISTORY +The +.Nm +manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +It first appeared in +.Fx 15.0 .