DTRACE_PROFILE(4)      FreeBSD Kernel Interfaces Manual      DTRACE_PROFILE(4)

NAME

     dtrace_profile - a DTrace provider for firing probes at a given time
     interval

SYNOPSIS

     profile:::profile-rate[unit]
     profile:::tick-rate[unit]

DESCRIPTION

     The profile provider implements three special probes related to the life
     cycle of the DTrace program itself.

Probes

     The profile:::profile probes fire on all CPUs and are suitable for
     measuring the whole system periodically.

     The profile:::tick probes fire on a single CPU, potentially a different
     one every time.  They are useful, e.g., for printing partial results
     periodically.

Rate and Time Units

     The profile provider probes will fire at the specified rate.

     The default unit is hz.  The profile provider supports the following time
     units:

           Time Unit   Definition
           ns, nsec    nanoseconds
           us, usec    microseconds
           ms, msec    milliseconds
           s, sec      seconds
           m, min      minutes
           h, hour     hours
           d, day      days
           hz          Hertz (frequency per second)

Probe Arguments

     The arguments of the profile provider probes are:

     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.

     arg1  The PC in the user process when the probe triggered, or 0 if the
           process was in the kernel when the probe triggered.

     Use arguments arg0 and arg1 to tell if the profile provider probe fired
     in the kernel or in the userspace context.

IMPLEMENTATION NOTES

     The sysctl(8) variable kern.dtrace.profile.aframes controls the number of
     skipped artificial frames for the profile provider.

EXAMPLES

Example 1: Profiling On-CPU Kernel Stack Traces

     The following DTrace one-liner uses the profile provider to collect stack
     traces over 60 seconds.

           dtrace -x stackframes=100 -n 'profile-197 /arg0/ {@[stack()] = count();} tick-60s {exit(0);}

     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.

     Option -x stackframes=100 increases the maximum number of kernel stack
     frames to unwind during stack().

     Checking if arg0 is not zero makes sure that profiling happens when the
     program is in the kernel context.

     Refer to https://www.brendangregg.com/flamegraphs.html to learn about
     generating flame graphs from the obtained stack traces.

SEE ALSO

     dtrace(1), tracing(7)

     The illumos Dynamic Tracing Guide,
     https://www.illumos.org/books/dtrace/chp-profile.html, 2008, Chapter
     profile Provider.

     Brendan Gregg and Jim Mauro, DTrace: Dynamic Tracing in Oracle Solaris,
     Mac OS X and FreeBSD, Prentice Hall,
     https://www.brendangregg.com/dtracebook/, pp. 24-25, 2011.

AUTHORS

     This manual page was written by Mateusz Piotrowski <0mp@FreeBSD.org>.

FreeBSD 15.1-STABLE-HBSD         July 14, 2025               DTRACE_PROFILE(4)