DTRACE_PROFILE(4)

📦 version 15.1, in freebsd 15.1, nixpkgs unstable

💫 DTRACE_PROFILE(4) 💫

okay so real talk — this is a page from the Kernel Interfaces Manual, and it's all about dtrace_profile, a DTrace provider that fires probes at a given time interval. bestie, it's literally a metronome for your kernel. ✨

🌸 NAME 🌸

dtrace_profile — a DTrace provider for firing probes at a given time interval. that's it, that's the vibe. 🎀

🦋 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. yes, three. no cap.

✨ Probes ✨

  • profile:::profile — these probes fire on all CPUs and are suitable for measuring the whole system periodically. like, the entire system. main character energy for your whole machine. 👑
  • profile:::tick — these probes fire on a single CPU, and potentially a different one every single time (chaotic, honestly). super useful, e.g., for printing partial results periodically. 🕰️

🎀 Rate and Time Units 🎀

The profile provider probes will fire at the specified rate. simple as that.

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

  • 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. it's giving "which world are we in rn" 🌈

🔥 IMPLEMENTATION NOTES 🔥

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

👑 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. iconic behavior honestly.

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 — like, it's deliberately weird on purpose, iykyk. 🧚

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. 🔥 (literally flame graphs, the name is not a drill)

💜 SEE ALSO 💜

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>. thank you mateusz, you ate. 🫶

okay that's the whole page bestie, you're now officially a profile-provider knower. go forth and sample responsibly. 🦋💖

big slay sign-off: this came from the fine folks over at Debian, dated July 14, 2025 — periodt. 💅✨

📦 where this page comes from