1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd July 14, 2025 7.Dt DTRACE_PROFILE 4 8.Os 9.Sh NAME 10.Nm dtrace_profile 11.Nd a DTrace provider for firing probes at a given time interval 12.Sh SYNOPSIS 13.Nm profile Ns Cm :::profile- Ns Ar rate Ns Op Ar unit 14.Nm profile Ns Cm :::tick- Ns Ar rate Ns Op Ar unit 15.Sh DESCRIPTION 16The 17.Nm profile 18provider implements three special probes related to the life cycle of the 19DTrace program itself. 20.Ss Probes 21The 22.Nm profile Ns Cm :::profile 23probes fire on all CPUs and are suitable for measuring the whole system 24periodically. 25.Pp 26The 27.Nm profile Ns Cm :::tick 28probes fire on a single CPU, potentially a different one every time. 29They are useful, e.g., for printing partial results periodically. 30.Ss Rate and Time Units 31The 32.Nm profile 33provider probes will fire at the specified 34.Ar rate . 35.Pp 36The default unit is 37.Cm hz . 38The 39.Nm profile 40provider supports the following time units: 41.Bl -column -offset indent "ns, nsec" "Definition" 42.It Sy Time Unit Ta Sy Definition 43.It Cm ns , nsec Ta nanoseconds 44.It Cm us , usec Ta microseconds 45.It Cm ms , msec Ta milliseconds 46.It Cm s , sec Ta seconds 47.It Cm m , min Ta minutes 48.It Cm h , hour Ta hours 49.It Cm d , day Ta days 50.It Cm hz Ta Hertz (frequency per second) 51.El 52.Ss Probe Arguments 53The arguments of the 54.Nm profile 55provider probes 56are: 57.Bl -tag -width arg0 58.It Va arg0 59The PC (program counter) in the kernel when the probe triggered, 60or 0 if the process was not in the kernel at that time. 61.It Va arg1 62The PC in the user process when the probe triggered, 63or 0 if the process was in the kernel when the probe triggered. 64.El 65.Pp 66Use arguments 67.Va arg0 68and 69.Va arg1 70to tell if the 71.Nm profile 72provider probe fired in the kernel or in the userspace context. 73.Sh IMPLEMENTATION NOTES 74The 75.Xr sysctl 8 76variable 77.Va kern.dtrace.profile.aframes 78controls the number of skipped artificial frames for 79the 80.Nm profile 81provider. 82.Sh EXAMPLES 83.Ss Example 1 : Profiling On-CPU Kernel Stack Traces 84The following DTrace one-liner uses the 85.Nm profile 86provider to collect stack traces over 60 seconds. 87.\" XXX: Keep on one line for easier copy-pasting. 88.Bd -literal -offset indent 89dtrace -x stackframes=100 -n 'profile-197 /arg0/ {@[stack()] = count();} tick-60s {exit(0);} 90.Ed 91.Pp 92The system is profiled at the 197 Hz to avoid sampling in lockstep 93with other periodic activities. 94This unnatural frequency minimizes the chance of overlapping with other events. 95.Pp 96Option 97.Fl x Cm stackframes=100 98increases the maximum number of kernel stack frames to unwind during 99.Fn stack . 100.Pp 101Checking if 102.Ar arg0 103is not zero makes sure that profiling happens 104when the program is in the kernel context. 105.Pp 106Refer to 107.Lk https://www.brendangregg.com/flamegraphs.html 108to learn about generating flame graphs from the obtained stack traces. 109.Sh SEE ALSO 110.Xr dtrace 1 , 111.Xr tracing 7 112.Rs 113.%B The illumos Dynamic Tracing Guide 114.%O Chapter profile Provider 115.%D 2008 116.%U https://www.illumos.org/books/dtrace/chp-profile.html 117.Re 118.Rs 119.%A Brendan Gregg 120.%A Jim Mauro 121.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD 122.%I Prentice Hall 123.%P pp. 24\(en25 124.%D 2011 125.%U https://www.brendangregg.com/dtracebook/ 126.Re 127.Sh AUTHORS 128This manual page was written by 129.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 130