diff options
Diffstat (limited to 'documentation/content/en/books/handbook/dtrace/_index.po')
| -rw-r--r-- | documentation/content/en/books/handbook/dtrace/_index.po | 496 |
1 files changed, 496 insertions, 0 deletions
diff --git a/documentation/content/en/books/handbook/dtrace/_index.po b/documentation/content/en/books/handbook/dtrace/_index.po new file mode 100644 index 0000000000..868b8dfd63 --- /dev/null +++ b/documentation/content/en/books/handbook/dtrace/_index.po @@ -0,0 +1,496 @@ +# 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 <LL@li.org>\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 "" |