From nobody Mon Jul 14 16:36:33 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bgnyT2jkzz61xFh; Mon, 14 Jul 2025 16:36:33 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bgnyT1SSfz41Gh; Mon, 14 Jul 2025 16:36:33 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752510993; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=k5TUfC3QeN1W5Ka974YaeeoPkh/x4dO0tZs0y2eEOpU=; b=mGPv0Bgip9+sBIYEA8tKCCoruz+UxHJ5jrFNdzulLINUTXo7ZyDIJS99ccOgL0dNjtXzDz TorP8/y7KFGmF3eIUSwYYR2fX9NogNkJdy9fgdZgzqnpqqAQt34sn8gG4f+GD/nZ5hcwYV pQERjbTp5+LeD7n31K/uO+u82ixrpcyPK6bjQv9kL5HDH+ucdzr1z/H/IiYdEiLIAadxCa iz2Bewj2KFNPOYXjILp4EOK5dSf9CQBJb92DoaVUxnCqP0bLpvdRcJO93bvDR/SYiCV9zY g//v0eTTWUw0U3jNrjLF+AwmKdP41XRN0q3f2uX3p76mNpruO6dErm3s9Z+Y7Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752510993; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=k5TUfC3QeN1W5Ka974YaeeoPkh/x4dO0tZs0y2eEOpU=; b=Kj8v1vEMWNNEnxI3ZYMel2qzpyDXc/Mgyd0O30PV2SUURCqhmvY3ton/btUYP6sqsF9ikF lc3L2s3QWSeOsCNv0FtN73/Rd8vnX5dbDPZLCQ8LEKNJcSy3onZRXRRlXtQkViR49gaZp7 GkNwaZrn3+AlkqRKnd66Wsf0vSJqYb6k8l8PtSxoZAWihl2nCNHSdXPyQX3cl4OWEljKpn hdxI9qqYji39npgkqy9UlUY2ctn94YT8GkdCZYhWOk+lJOb5AzCPNbqUHm/3bIhu+gLPTu 1r1s+0aWpQcGFF6GImP1lFQqj+ya5/UjfWXmlmbAVI0ppujrUHCI3LLSpjwoyA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1752510993; a=rsa-sha256; cv=none; b=cXtuvujbCEZZzHsaIOVKBIT1WC4L+7IXlW/tn10bALRCLwRuVxxYqgu3E0J0ZUAS2mfhW+ ZF6oaWhYniOEd7zcrFj5W7GBkbsIGwol4GM5uiHOTNITkxbAnJEr00mVaKJbvZKfOzsbqU WdR2cR4inFAdHlqfL5CNhOZ6nJfStICgGpTzOTyrFF6NR+cYRPXJ0exkaE9AgvtOPEEujL uAZghwh0Efn61/o2ATI2Ko5KKZKYDAPnBgQDDxIRaLXC2HHUmp2RhWyLgLOemVsBetGAqX a2/NerdSYxCCswW5/478Jp1U3MpVQ5fj3HuNxxKTsHAnW3UlctMmV9DZjL/ruw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bgnyT0dMdz12Nt; Mon, 14 Jul 2025 16:36:33 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56EGaXpG045528; Mon, 14 Jul 2025 16:36:33 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56EGaX8G045525; Mon, 14 Jul 2025 16:36:33 GMT (envelope-from git) Date: Mon, 14 Jul 2025 16:36:33 GMT Message-Id: <202507141636.56EGaX8G045525@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: 46efd2ceca73 - main - dtrace_profile.4: Document the DTrace profile provider List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: 0mp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 46efd2ceca736a20f06a730921574065047c01fe Auto-Submitted: auto-generated The branch main has been updated by 0mp: URL: https://cgit.FreeBSD.org/src/commit/?id=46efd2ceca736a20f06a730921574065047c01fe commit 46efd2ceca736a20f06a730921574065047c01fe Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2025-07-12 13:49:11 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2025-07-14 16:35:01 +0000 dtrace_profile.4: Document the DTrace profile provider Event: Berlin Hackathon 202507 Reviewed by: bcr, christos Relnotes: yes Differential Revision: https://reviews.freebsd.org/D51278 --- cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | 1 + share/man/man4/Makefile | 1 + share/man/man4/dtrace_profile.4 | 129 +++++++++++++++++++++++++++ 3 files changed, 131 insertions(+) diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 index f3d7a49e0e78..bcd23c1789be 100644 --- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 +++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 @@ -1229,6 +1229,7 @@ Invalid command line options or arguments were specified. .Xr dtrace_kinst 4 , .Xr dtrace_lockstat 4 , .Xr dtrace_proc 4 , +.Xr dtrace_profile 4 , .Xr dtrace_sched 4 , .Xr dtrace_sctp 4 , .Xr dtrace_tcp 4 , diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 5648fd2c1a84..5e60f00bc09f 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -986,6 +986,7 @@ _dtrace_provs= dtrace_audit.4 \ dtrace_kinst.4 \ dtrace_lockstat.4 \ dtrace_proc.4 \ + dtrace_profile.4 \ dtrace_sched.4 \ dtrace_sctp.4 \ dtrace_tcp.4 \ diff --git a/share/man/man4/dtrace_profile.4 b/share/man/man4/dtrace_profile.4 new file mode 100644 index 000000000000..07f86663d60a --- /dev/null +++ b/share/man/man4/dtrace_profile.4 @@ -0,0 +1,129 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt DTRACE_PROFILE 4 +.Os +.Sh NAME +.Nm dtrace_profile +.Nd a DTrace provider for firing probes at a given time interval +.Sh SYNOPSIS +.Nm profile Ns Cm :::profile- Ns Ar rate Ns Op Ar unit +.Nm profile Ns Cm :::tick- Ns Ar rate Ns Op Ar unit +.Sh DESCRIPTION +The +.Nm profile +provider implements three special probes related to the life cycle of the +DTrace program itself. +.Ss Probes +The +.Nm profile Ns Cm :::profile +probes fire on all CPUs and are suitable for measuring the whole system +periodically. +.Pp +The +.Nm profile Ns Cm :::tick +probes fire on a single CPU, potentially a different one every time. +They are useful, e.g., for printing partial results periodically. +.Ss Rate and Time Units +The +.Nm profile +provider probes will fire at the specified +.Ar rate . +.Pp +The default unit is +.Cm hz . +The +.Nm profile +provider supports the following time units: +.Bl -column -offset indent "ns, nsec" "Definition" +.It Sy Time Unit Ta Sy Definition +.It Cm ns , nsec Ta nanoseconds +.It Cm us , usec Ta microseconds +.It Cm ms , msec Ta milliseconds +.It Cm s , sec Ta seconds +.It Cm m , min Ta minutes +.It Cm h , hour Ta hours +.It Cm d , day Ta days +.It Cm hz Ta Hertz (frequency per second) +.El +.Ss Probe Arguments +The arguments of the +.Nm profile +provider probes +are: +.Bl -tag -width arg0 +.It Va 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. +.It Va arg1 +The PC in the user process when the probe triggered, +or 0 if the process was in the kernel when the probe triggered. +.El +.Pp +Use arguments +.Va arg0 +and +.Va arg1 +to tell if the +.Nm profile +provider probe fired in the kernel or in the userspace context. +.Sh IMPLEMENTATION NOTES +The +.Xr sysctl 8 +variable +.Va kern.dtrace.profile.aframes +controls the number of skipped artificial frames for +the +.Nm profile +provider. +.Sh EXAMPLES +.Ss Example 1 : Profiling On-CPU Kernel Stack Traces +The following DTrace one-liner uses the +.Nm profile +provider to collect stack traces over 60 seconds. +.\" XXX: Keep on one line for easier copy-pasting. +.Bd -literal -offset indent +dtrace -x stackframes=100 -n 'profile-197 /arg0/ {@[stack()] = count();} tick-60s {exit(0);} +.Ed +.Pp +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. +.Pp +Option +.Fl x Cm stackframes=100 +increases the maximum number of kernel stack frames to unwind during +.Fn stack . +.Pp +Checking if +.Ar arg0 +is not zero makes sure that profiling happens +when the program is in the kernel context. +.Pp +Refer to +.Lk https://www.brendangregg.com/flamegraphs.html +to learn about generating flame graphs from the obtained stack traces. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter profile Provider +.%D 2008 +.%U https://www.illumos.org/books/dtrace/chp-profile.html +.Re +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%P pp. 24\(en25 +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .