The branch main has been updated by 0mp:
URL:
https://cgit.FreeBSD.org/src/commit/?id=46efd2ceca736a20f06a730921574065047c01fe
commit 46efd2ceca736a20f06a730921574065047c01fe
Author: Mateusz Piotrowski <0...@freebsd.org>
AuthorDate: 2025-07-12 13:49:11 +0000
Commit: Mateusz Piotrowski <0...@freebsd.org>
CommitDate: 2025-07-14 16:35:01 +0000
dtrace_profile.4: Document the DTrace profile provider
Event: Berlin Hackathon 202507
Reviewed by: bcr, christos
Relnotes: yes
Differential Revision: https://reviews.freebsd.org/D51278
---
cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | 1 +
share/man/man4/Makefile | 1 +
share/man/man4/dtrace_profile.4 | 129 +++++++++++++++++++++++++++
3 files changed, 131 insertions(+)
diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index f3d7a49e0e78..bcd23c1789be 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -1229,6 +1229,7 @@ Invalid command line options or arguments were specified.
.Xr dtrace_kinst 4 ,
.Xr dtrace_lockstat 4 ,
.Xr dtrace_proc 4 ,
+.Xr dtrace_profile 4 ,
.Xr dtrace_sched 4 ,
.Xr dtrace_sctp 4 ,
.Xr dtrace_tcp 4 ,
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 5648fd2c1a84..5e60f00bc09f 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -986,6 +986,7 @@ _dtrace_provs= dtrace_audit.4 \
dtrace_kinst.4 \
dtrace_lockstat.4 \
dtrace_proc.4 \
+ dtrace_profile.4 \
dtrace_sched.4 \
dtrace_sctp.4 \
dtrace_tcp.4 \
diff --git a/share/man/man4/dtrace_profile.4 b/share/man/man4/dtrace_profile.4
new file mode 100644
index 000000000000..07f86663d60a
--- /dev/null
+++ b/share/man/man4/dtrace_profile.4
@@ -0,0 +1,129 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0...@freebsd.org>
+.\"
+.Dd July 14, 2025
+.Dt DTRACE_PROFILE 4
+.Os
+.Sh NAME
+.Nm dtrace_profile
+.Nd a DTrace provider for firing probes at a given time interval
+.Sh SYNOPSIS
+.Nm profile Ns Cm :::profile- Ns Ar rate Ns Op Ar unit
+.Nm profile Ns Cm :::tick- Ns Ar rate Ns Op Ar unit
+.Sh DESCRIPTION
+The
+.Nm profile
+provider implements three special probes related to the life cycle of the
+DTrace program itself.
+.Ss Probes
+The
+.Nm profile Ns Cm :::profile
+probes fire on all CPUs and are suitable for measuring the whole system
+periodically.
+.Pp
+The
+.Nm profile Ns Cm :::tick
+probes fire on a single CPU, potentially a different one every time.
+They are useful, e.g., for printing partial results periodically.
+.Ss Rate and Time Units
+The
+.Nm profile
+provider probes will fire at the specified
+.Ar rate .
+.Pp
+The default unit is
+.Cm hz .
+The
+.Nm profile
+provider supports the following time units:
+.Bl -column -offset indent "ns, nsec" "Definition"
+.It Sy Time Unit Ta Sy Definition
+.It Cm ns , nsec Ta nanoseconds
+.It Cm us , usec Ta microseconds
+.It Cm ms , msec Ta milliseconds
+.It Cm s , sec Ta seconds
+.It Cm m , min Ta minutes
+.It Cm h , hour Ta hours
+.It Cm d , day Ta days
+.It Cm hz Ta Hertz (frequency per second)
+.El
+.Ss Probe Arguments
+The arguments of the
+.Nm profile
+provider probes
+are:
+.Bl -tag -width arg0
+.It Va arg0
+The PC (program counter) in the kernel when the probe triggered,
+or 0 if the process was not in the kernel at that time.
+.It Va arg1
+The PC in the user process when the probe triggered,
+or 0 if the process was in the kernel when the probe triggered.
+.El
+.Pp
+Use arguments
+.Va arg0
+and
+.Va arg1
+to tell if the
+.Nm profile
+provider probe fired in the kernel or in the userspace context.
+.Sh IMPLEMENTATION NOTES
+The
+.Xr sysctl 8
+variable
+.Va kern.dtrace.profile.aframes
+controls the number of skipped artificial frames for
+the
+.Nm profile
+provider.
+.Sh EXAMPLES
+.Ss Example 1 : Profiling On-CPU Kernel Stack Traces
+The following DTrace one-liner uses the
+.Nm profile
+provider to collect stack traces over 60 seconds.
+.\" XXX: Keep on one line for easier copy-pasting.
+.Bd -literal -offset indent
+dtrace -x stackframes=100 -n 'profile-197 /arg0/ {@[stack()] = count();}
tick-60s {exit(0);}
+.Ed
+.Pp
+The system is profiled at the 197 Hz to avoid sampling in lockstep
+with other periodic activities.
+This unnatural frequency minimizes the chance of overlapping with other events.
+.Pp
+Option
+.Fl x Cm stackframes=100
+increases the maximum number of kernel stack frames to unwind during
+.Fn stack .
+.Pp
+Checking if
+.Ar arg0
+is not zero makes sure that profiling happens
+when the program is in the kernel context.
+.Pp
+Refer to
+.Lk https://www.brendangregg.com/flamegraphs.html
+to learn about generating flame graphs from the obtained stack traces.
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr tracing 7
+.Rs
+.%B The illumos Dynamic Tracing Guide
+.%O Chapter profile Provider
+.%D 2008
+.%U https://www.illumos.org/books/dtrace/chp-profile.html
+.Re
+.Rs
+.%A Brendan Gregg
+.%A Jim Mauro
+.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+.%I Prentice Hall
+.%P pp. 24\(en25
+.%D 2011
+.%U https://www.brendangregg.com/dtracebook/
+.Re
+.Sh AUTHORS
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0...@freebsd.org .
