mirror of
https://github.com/opnsense/src.git
synced 2026-06-13 18:50:31 -04:00
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
This commit is contained in:
Mateusz Piotrowski
parent
0d0d6378ad
commit
46efd2ceca
3 changed files with 131 additions and 0 deletions
|
|
@ -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 ,
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
|
|||
129
share/man/man4/dtrace_profile.4
Normal file
129
share/man/man4/dtrace_profile.4
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
.\"
|
||||
.\" SPDX-License-Identifier: BSD-2-Clause
|
||||
.\"
|
||||
.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@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 0mp@FreeBSD.org .
|
||||
Loading…
Reference in a new issue