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, Chapter profile Provider, 2008, https://www.illumos.org/books/dtrace/chp-profile.html. Brendan Gregg, Jim Mauro, DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD, Prentice Hall, pp. 24–25, 2011, https://www.brendangregg.com/dtracebook/.

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