From nobody Thu Jul 17 19:48:46 2025 X-Original-To: dev-commits-doc-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 4bjk4v4HhQz62BBr for ; Thu, 17 Jul 2025 19:48:47 +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 4bjk4v14FWz3fyq; Thu, 17 Jul 2025 19:48:47 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752781727; 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=QelF5+/PzH+1uoD14R6t67zxbC734GOACnvchnqbyhg=; b=fbp9gh2GiXyyrPSvRkoM6HS3dGlKn2ZZ481MT9237VzVfnN+cjjl+A/Tj+0UYL+gCT7WOV SKcaGCQM+l2XBf5FMY3EvhF1BuR8bJhFHa5aT7OCO5DHhgdTH40Jn5eQjZrmKgdkqKIXaH RWiVtleSfiaEvQ4hyt9+c7W3SVin3hTMYKKq4o0PTYFhP/zetaau2wexfBtyJt4bzsPJuB 5TMcz/h+UCpX26iPD8E56UYdjxZVlvVnjgNfFpqR5mcNrG6pIuI/hcIBhyi9EXBC6T7qSm p9KtSXfjGW2aY0jYKQYF6VtgQjQ/WrasHQKrtbBu/zwv5tMWH+UziGsUjBJgHQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752781727; 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=QelF5+/PzH+1uoD14R6t67zxbC734GOACnvchnqbyhg=; b=cukNtNHq508ddZsX8JwwszRKPwTfiLI2t529xAV+njOoi6WjqK2xItKsP3S7d9pzzej0Rd vJGUkK5EUep3bL99G8j2PYmUCduVjBYzhp/bEJ1NJrfVhpDlPikEdX8eKa/UMhtU5wwchW ZUkGzdf26rwjp26tvZFX7b4Jq86yyroxMvUHpsjbZO3mhtnSdqPLyKUAAXLYtl/Rj1HyL+ a+4gOZ53MX7+Ikg5oLwJMLG3mg3RzFCtHbuNlLpmI4H/xVf3s9Wu9Kud8plKhd2y7K42B5 mX0xpxRneqYJ9not9Urgk6xzcgjrIFxYR1K32deGDacgVC9AlhZC5KFMivGWCQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1752781727; a=rsa-sha256; cv=none; b=lEfRyY5jeBaaCiVE9wxT+FRu9ZiQ+RIZuUIeT0fkcpUHsBXAYx5zWjKiLVWa4iqIv1++AH NM8hVfcRiJEf6MUzDWHSHhqReqvNQrj55C9yApnbMMwi6o6XPv2RNjBVdP9oxmg0tIcF4I xA3z5zPwsxNdp+S8iVdmnXxX2FTwn/GuTOYBmV6nQU7ZEGTNzJE/2pP65rfKM/u5UBxiVf NVDruj8d9rEkiT4EUhmQeqKklAgvUsYKnVlbwA3bK1cVq6o/sX9P+lfE+yWhIHkHG1Mk4m w19T9TjCZGB48xuP+SzrkJAWbn3vxT9z5ie8wvGrRFrk6kutdBAeBQgzgG9dLg== 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 4bjk4v05gfz17ph; Thu, 17 Jul 2025 19:48:47 +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 56HJmkWp051833; Thu, 17 Jul 2025 19:48:46 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56HJmkSV051830; Thu, 17 Jul 2025 19:48:46 GMT (envelope-from git) Date: Thu, 17 Jul 2025 19:48:46 GMT Message-Id: <202507171948.56HJmkSV051830@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: 13ac0282a8 - main - handbook/dtrace: Add references and refresh some paragraphs List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-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: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 13ac0282a853954f15705906150ab6dd91f20ac2 Auto-Submitted: auto-generated The branch main has been updated by 0mp: URL: https://cgit.FreeBSD.org/doc/commit/?id=13ac0282a853954f15705906150ab6dd91f20ac2 commit 13ac0282a853954f15705906150ab6dd91f20ac2 Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2025-07-17 19:46:34 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2025-07-17 19:48:41 +0000 handbook/dtrace: Add references and refresh some paragraphs - Reference manual pages where appropriate - Rewrite some paragraphs for better clarity - Do some minor wordsmithing - Do not explain how ksh is needed for the DTrace Toolkit. That's what RUN_DEPENDS are for. --- .../content/en/books/handbook/dtrace/_index.adoc | 32 ++++++++++------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/documentation/content/en/books/handbook/dtrace/_index.adoc b/documentation/content/en/books/handbook/dtrace/_index.adoc index 26a50a890d..7e9dfc52f4 100644 --- a/documentation/content/en/books/handbook/dtrace/_index.adoc +++ b/documentation/content/en/books/handbook/dtrace/_index.adoc @@ -88,18 +88,18 @@ To load all of the necessary modules: # kldload dtraceall .... -Beginning with FreeBSD 10.0-RELEASE, the modules are automatically loaded when `dtrace` is run. +Beginning with FreeBSD 10.0-RELEASE, the modules are automatically loaded when man:dtrace[1] is run. -FreeBSD uses the `DDB_CTF` kernel option to enable support for loading `CTF` data from kernel modules and the kernel itself. -`CTF` is the Solaris(TM) Compact C Type Format which encapsulates a reduced form of debugging information similar to `DWARF` and the venerable stabs. -`CTF` data is added to binaries by the `ctfconvert` and `ctfmerge` build tools. +FreeBSD uses the `DDB_CTF` kernel option to enable support for loading man:ctf[5] data from kernel modules and the kernel itself. +`CTF` is the Solaris(TM) Compact C Type Format which encapsulates a reduced form of debugging information similar to `DWARF` and the venerable stabs. +`CTF` data is added to binaries by the man:ctfconvert[1] and man:ctfmerge[1] build tools. The `ctfconvert` utility parses `DWARF``ELF` debug sections created by the compiler and `ctfmerge` merges `CTF``ELF` sections from objects into either executables or shared libraries. Some different providers exist for FreeBSD than for Solaris(TM). -Most notable is the `dtmalloc` provider, which allows tracing `malloc()` by type in the FreeBSD kernel. +Most notable is the `dtmalloc` provider, which allows tracing man:malloc[9] by type in the FreeBSD kernel. Some of the providers found in Solaris(TM), such as `cpc` and `mib`, are not present in FreeBSD. These may appear in future versions of FreeBSD. -Moreover, some of the providers available in both operating systems are not compatible, in the sense that their probes have different argument types. +Moreover, some of the providers available in both operating systems are not compatible, in the sense that their probes have different argument types. Thus, `D` scripts written on Solaris(TM) may or may not work unmodified on FreeBSD, and vice versa. Due to security differences, only `root` may use DTrace on FreeBSD. @@ -131,17 +131,12 @@ Users of the AMD64 architecture should also add this line: options KDTRACE_FRAME .... -This option provides support for `FBT`. +This option provides support for man:dtrace_fbt[4]. While DTrace will work without this option, there will be limited support for function boundary tracing. -Once the FreeBSD system has rebooted into the new kernel, or the DTrace kernel modules have been loaded using `kldload dtraceall`, the system will need support for the Korn shell as the DTrace Toolkit has several utilities written in `ksh`. -Make sure that the package:shells/ksh93[] package or port is installed. -It is also possible to run these tools under package:shells/pdksh[] or package:shells/mksh[]. - -Finally, install the current DTrace Toolkit, a collection of ready-made scripts for collecting system information. -There are scripts to check open files, memory, `CPU` usage, and a lot more. -FreeBSD 10 installs a few of these scripts into [.filename]#/usr/share/dtrace#. -On other FreeBSD versions, or to install the full DTrace Toolkit, use the package:sysutils/dtrace-toolkit[] package or port. +Once the FreeBSD system has rebooted into the new kernel, or the DTrace kernel modules have been loaded using `kldload dtraceall`, install the current DTrace Toolkit (package:sysutils/dtrace-toolkit[]), a collection of ready-made scripts for collecting system information. +There are scripts to check open files, memory, CPU usage, and a lot more. +FreeBSD includes some scripts in the base system as well; see [.filename]#/usr/share/dtrace#. [NOTE] ==== @@ -152,7 +147,8 @@ Not all of the scripts found in the DTrace Toolkit will work as-is on FreeBSD an The DTrace Toolkit includes many scripts in the special language of DTrace. This language is called the D language and it is very similar to C++. An in depth discussion of the language is beyond the scope of this document. -It is covered extensively in the https://www.illumos.org/books/dtrace/bookinfo.html[illumos Dynamic Tracing Guide]. +Refer to the FreeBSD man:d[7] manual page for an overview of the D language on FreeBSD. +The D language is also covered extensively in the https://www.illumos.org/books/dtrace/bookinfo.html[illumos Dynamic Tracing Guide]. [[dtrace-out-of-kernel]] == Enabling DTrace in Out-of-Kernel Modules @@ -183,7 +179,7 @@ To view all probes, the administrator can execute the following command: # dtrace -l | more .... -Each probe has an `ID`, a `PROVIDER` (dtrace or fbt), a `MODULE`, and a `FUNCTION NAME`. +Each probe has an `ID`, a `PROVIDER` (e.g., `dtrace` or `fbt`), a `MODULE`, and a `FUNCTION NAME`. Refer to man:dtrace[1] for more information about this command. The examples in this section provide an overview of how to use two of the fully supported scripts from the DTrace Toolkit: the [.filename]#hotkernel# and [.filename]#procsystime# scripts. @@ -288,4 +284,4 @@ Elapsed Times for processes csh, read 3988049784 .... -As shown, the `read()` system call used the most time in nanoseconds while the `getpid()` system call used the least amount of time. +As shown, the man:read[2] system call used the most time in nanoseconds while the man:getpid[2] system call used the least amount of time.