The branch main has been updated by 0mp:
URL:
https://cgit.FreeBSD.org/src/commit/?id=c29459f901dc73e1ebe1e654da2677cc0b7bd296
commit c29459f901dc73e1ebe1e654da2677cc0b7bd296
Author: Mateusz Piotrowski <0...@freebsd.org>
AuthorDate: 2025-06-14 17:38:12 +0000
Commit: Mateusz Piotrowski <0...@freebsd.org>
CommitDate: 2025-06-18 22:15:26 +0000
tracing.7: Add a single reference point for tracing facilities in FreeBSD
FreeBSD has a fair number of tracing facilities. The new tracing(7)
manual page aims to provide a starting point for users to learn about
what is available.
Reviewed by: christos, bnovkov, markj, ziaee
Approved by: christos (mentor), bnovkov (mentor), markj (mentor)
Relnotes: yes
Differential Revision: https://reviews.freebsd.org/D50854
---
share/man/man7/Makefile | 1 +
share/man/man7/tracing.7 | 97 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 98 insertions(+)
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
@@ -30,6 +30,7 @@ MAN= arch.7 \
stdint.7 \
sticky.7 \
tests.7 \
+ tracing.7 \
tuning.7
MLINKS= intro.7 miscellaneous.7
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 <0...@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 0...@freebsd.org .
+It first appeared in
+.Fx 15.0 .
