Path: blob/main/documentation/content/en/books/handbook/dtrace/_index.po
18098 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-11-08 16:17+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/handbook/dtrace/_index.adoc:1 #, no-wrap msgid "This chapter explains how to use DTrace in FreeBSD" msgstr "" #. type: YAML Front Matter: part #: documentation/content/en/books/handbook/dtrace/_index.adoc:1 #, no-wrap msgid "Part III. System Administration" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/handbook/dtrace/_index.adoc:1 #, no-wrap msgid "Chapter 27. DTrace" msgstr "" #. type: Title = #: documentation/content/en/books/handbook/dtrace/_index.adoc:15 #, no-wrap msgid "DTrace" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/dtrace/_index.adoc:53 #, no-wrap msgid "Synopsis" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:57 msgid "" "DTrace, also known as Dynamic Tracing, was developed by Sun(TM) as a tool " "for locating performance bottlenecks in production and pre-production " "systems. In addition to diagnosing performance problems, DTrace can be used " "to help investigate and debug unexpected behavior in both the FreeBSD kernel " "and in userland programs." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:61 msgid "" "DTrace is a remarkable profiling tool, with an impressive array of features " "for diagnosing system issues. It may also be used to run pre-written " "scripts to take advantage of its capabilities. Users can author their own " "utilities using the DTrace D Language, allowing them to customize their " "profiling based on specific needs." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:65 msgid "" "The FreeBSD implementation provides full support for kernel DTrace and " "experimental support for userland DTrace. Userland DTrace allows users to " "perform function boundary tracing for userland programs using the `pid` " "provider, and to insert static probes into userland programs for later " "tracing. Some ports, such as package:databases/postgresql12-server[] and " "package:lang/php74[] have a DTrace option to enable static probes." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:67 msgid "" "The official guide to DTrace is maintained by the illumos project at https://" "illumos.org/books/dtrace/bookinfo.html[illumos Dynamic Tracing Guide]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:69 msgid "Read this chapter to learn:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:71 msgid "What DTrace is and what features it provides." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:72 msgid "" "Differences between the Solaris(TM) DTrace implementation and the one " "provided by FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:73 msgid "How to enable and use DTrace on FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:75 msgid "Before reading this chapter:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:77 msgid "" "Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD " "Basics])." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:78 msgid "" "Have some familiarity with security and how it pertains to FreeBSD " "(crossref:security[security,Security])." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/dtrace/_index.adoc:80 #, no-wrap msgid "Implementation Differences" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:85 msgid "" "While the DTrace in FreeBSD is similar to that found in Solaris(TM), " "differences do exist. The primary difference is that in FreeBSD, DTrace is " "implemented as a set of kernel modules and DTrace can not be used until the " "modules are loaded. To load all of the necessary modules:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:89 #, no-wrap msgid "# kldload dtraceall\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:92 msgid "" "Beginning with FreeBSD 10.0-RELEASE, the modules are automatically loaded " "when man:dtrace[1] is run." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:97 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:104 msgid "" "Some different providers exist for FreeBSD than for Solaris(TM). 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`, 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. Thus, `D` scripts written on Solaris(TM) may or " "may not work unmodified on FreeBSD, and vice versa." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:108 msgid "" "Due to security differences, only `root` may use DTrace on FreeBSD. " "Solaris(TM) has a few low level security checks which do not yet exist in " "FreeBSD. As such, the [.filename]#/dev/dtrace/dtrace# is strictly limited " "to `root`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:112 msgid "" "DTrace falls under the Common Development and Distribution License (`CDDL`) " "license. To view this license on FreeBSD, see [.filename]#/usr/src/cddl/" "contrib/opensolaris/OPENSOLARIS.LICENSE# or view it online at http://" "opensource.org/licenses/CDDL-1.0[http://opensource.org/licenses/CDDL-1.0]. " "While a FreeBSD kernel with DTrace support is `BSD` licensed, the `CDDL` is " "used when the modules are distributed in binary form or the binaries are " "loaded." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/dtrace/_index.adoc:114 #, no-wrap msgid "Enabling DTrace Support" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:118 msgid "" "In FreeBSD 9.2 and 10.0, DTrace support is built into the " "[.filename]#GENERIC# kernel. Users of earlier versions of FreeBSD or who " "prefer to statically compile in DTrace support should add the following " "lines to a custom kernel configuration file and recompile the kernel using " "the instructions in crossref:kernelconfig[kernelconfig,Configuring the " "FreeBSD Kernel]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:125 #, no-wrap msgid "" "options KDTRACE_HOOKS\n" "options DDB_CTF\n" "makeoptions\tDEBUG=-g\n" "makeoptions\tWITH_CTF=1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:128 msgid "Users of the AMD64 architecture should also add this line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:132 #, no-wrap msgid "options KDTRACE_FRAME\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:136 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:140 msgid "" "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#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:145 msgid "" "The scripts found in [.filename]#/usr/share/dtrace# have been specifically " "ported to FreeBSD. Not all of the scripts found in the DTrace Toolkit will " "work as-is on FreeBSD and some scripts may require some effort in order for " "them to work on FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:152 msgid "" "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. " "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]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/dtrace/_index.adoc:154 #, no-wrap msgid "Enabling DTrace in Out-of-Kernel Modules" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:157 msgid "" "To add DTrace support to an out-of-kernel module, which is useful for " "development and debugging, include the following line in the module's " "Makefile:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:161 #, no-wrap msgid "CFLAGS+= -DKDTRACE_HOOKS\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:165 msgid "" "This flag enables DTrace hooks during compilation, allowing for advanced " "debugging and monitoring of the module. Ensure to recompile the module " "after this modification to activate DTrace functionality." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/dtrace/_index.adoc:167 #, no-wrap msgid "Using DTrace" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:174 msgid "" "DTrace scripts consist of a list of one or more _probes_, or instrumentation " "points, where each probe is associated with an action. Whenever the " "condition for a probe is met, the associated action is executed. For " "example, an action may occur when a file is opened, a process is started, or " "a line of code is executed. The action might be to log some information or " "to modify context variables. The reading and writing of context variables " "allows probes to share information and to cooperatively analyze the " "correlation of different events." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:176 msgid "" "To view all probes, the administrator can execute the following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:180 #, no-wrap msgid "# dtrace -l | more\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:184 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:186 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:189 msgid "" "The [.filename]#hotkernel# script is designed to identify which function is " "using the most kernel time. It will produce output similar to the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:195 #, no-wrap msgid "" "# cd /usr/local/share/dtrace-toolkit\n" "# ./hotkernel\n" "Sampling... Hit Ctrl-C to end.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:199 msgid "" "As instructed, use the kbd:[Ctrl+C] key combination to stop the process. " "Upon termination, the script will display a list of kernel functions and " "timing information, sorting the output in increasing order of time:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:228 #, no-wrap msgid "" "kernel`_thread_lock_flags 2 0.0%\n" "0xc1097063 2 0.0%\n" "kernel`sched_userret 2 0.0%\n" "kernel`kern_select 2 0.0%\n" "kernel`generic_copyin 3 0.0%\n" "kernel`_mtx_assert 3 0.0%\n" "kernel`vm_fault 3 0.0%\n" "kernel`sopoll_generic 3 0.0%\n" "kernel`fixup_filename 4 0.0%\n" "kernel`_isitmyx 4 0.0%\n" "kernel`find_instance 4 0.0%\n" "kernel`_mtx_unlock_flags 5 0.0%\n" "kernel`syscall 5 0.0%\n" "kernel`DELAY 5 0.0%\n" "0xc108a253 6 0.0%\n" "kernel`witness_lock 7 0.0%\n" "kernel`read_aux_data_no_wait 7 0.0%\n" "kernel`Xint0x80_syscall 7 0.0%\n" "kernel`witness_checkorder 7 0.0%\n" "kernel`sse2_pagezero 8 0.0%\n" "kernel`strncmp 9 0.0%\n" "kernel`spinlock_exit 10 0.0%\n" "kernel`_mtx_lock_flags 11 0.0%\n" "kernel`witness_unlock 15 0.0%\n" "kernel`sched_idletd 137 0.3%\n" "0xc10981a5 42139 99.3%\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:232 msgid "" "This script will also work with kernel modules. To use this feature, run " "the script with `-m`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:251 #, no-wrap msgid "" "# ./hotkernel -m\n" "Sampling... Hit Ctrl-C to end.\n" "^C\n" "MODULE COUNT PCNT\n" "0xc107882e 1 0.0%\n" "0xc10e6aa4 1 0.0%\n" "0xc1076983 1 0.0%\n" "0xc109708a 1 0.0%\n" "0xc1075a5d 1 0.0%\n" "0xc1077325 1 0.0%\n" "0xc108a245 1 0.0%\n" "0xc107730d 1 0.0%\n" "0xc1097063 2 0.0%\n" "0xc108a253 73 0.0%\n" "kernel 874 0.4%\n" "0xc10981a5 213781 99.6%\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:257 msgid "" "The [.filename]#procsystime# script captures and prints the system call time " "usage for a given process `ID` (`PID`) or process name. In the following " "example, a new instance of [.filename]#/bin/csh# was spawned. Then, " "[.filename]#procsystime# was executed and remained waiting while a few " "commands were typed on the other incarnation of `csh`. These are the " "results of this test:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:263 #, no-wrap msgid "" "# ./procsystime -n csh\n" "Tracing... Hit Ctrl-C to end...\n" "^C\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:265 #, no-wrap msgid "Elapsed Times for processes csh,\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/dtrace/_index.adoc:285 #, no-wrap msgid "" " SYSCALL TIME (ns)\n" " getpid 6131\n" " sigreturn 8121\n" " close 19127\n" " fcntl 19959\n" " dup 26955\n" " setpgid 28070\n" " stat 31899\n" " setitimer 40938\n" " wait4 62717\n" " sigaction 67372\n" " sigprocmask 119091\n" " gettimeofday 183710\n" " write 263242\n" " execve 492547\n" " ioctl 770073\n" " vfork 3258923\n" " sigsuspend 6985124\n" " read 3988049784\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/dtrace/_index.adoc:287 msgid "" "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." msgstr ""