Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
DTRACE_PROFILE(4)	     Kernel Interfaces Manual	       DTRACE_PROFILE(4)

NAME
     dtrace_profile  --  a DTrace provider for firing probes at a given time in-
     terval

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 measur-
     ing 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	periodi-
     cally.

   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  gen-
     erating flame graphs from the obtained stack traces.

SEE ALSO
     dtrace(1), tracing(7)

     The      illumos	   Dynamic	Tracing     Guide,     https://www.illu-
     mos.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 ports 15.quarterly	  July 14, 2025 	       DTRACE_PROFILE(4)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dtrace_profile&sektion=4&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help