diff --git a/en_US.ISO8859-1/books/handbook/dtrace/Makefile b/en_US.ISO8859-1/books/handbook/dtrace/Makefile new file mode 100644 index 0000000000..0a0e6e03dc --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/dtrace/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= dtrace/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml b/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml new file mode 100644 index 0000000000..4ee9a15f7b --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml @@ -0,0 +1,385 @@ + + + + + + + + + Tom + Rhodes + Written by + + + + + DTrace + + DTrace, also known as Dynamic Tracing, was developed by + &sun; as a tool for locating performance bottlenecks + in production and pre-production systems. It is not, in any way, + a debugging tool, but a tool for real time system analysis to + locate performance and other issues. + + 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 may even author their own utilities using + the DTrace D Language, allowing them to customize their profiling + based on specific needs. + + + Synopsis + + DTrace + + DTrace support + DTrace + + + After reading this chapter, you will know: + + + + What DTrace is and what features it provides. + + + + Differences between the &solaris; DTrace implementation + and the one provided by &os;. + + + + How to enable and use DTrace on &os;. + + + + Before reading this chapter, you should: + + + + Understand &unix; and &os; basics + (). + + + + Be familiar with + the basics of kernel configuration/compilation + (). + + + + Have some familiarity with security and how it + pertains to &os; (). + + + + Understand how to obtain and rebuild the &os; sources + (). + + + + + + This feature is considered experimental. Some options + may be lacking in functionality, other parts may not work + at all. In time, this feature will be considered production + ready and this documentation will be altered to fit that + situation. + + + + + Implementation Differences + + While the DTrace in &os; is very similar to that found + in &solaris;, differences exist that should be explained before + continuing. The primary difference users will notice is that + on &os;, DTrace needs to be specifically enabled. There are + kernel options and modules which must be enabled for DTrace to + work properly. These will be explained later. + + There is a DDB_CTF kernel option which + is used to enable support for loading the CTF + data from kernel modules and the kernel itself. + CTF is the &solaris; Compressed C Type format + which encapsulates a reduced form of debugging information + similar to DWARF and the venerable stabs. + This CTF data is added to the binaries by the + ctfconvert and ctfmerge + build tools. The ctfconvert utility parses + DWARF debug ELF sections + created by the compiler and ctfmerge merges + CTF ELF sections from + objects into either executables or shared libraries. More on + how to enable this for the kernel and &os; build is + forthcoming. + + Some different providers exist for &os; than for &solaris;. + Most notable is the dtmalloc provider, which + allows tracing malloc() by type in the + &os; kernel. + + Only root may use DTrace on &os;. + This is related to security differences, &solaris; has a few + low level security checks which do not yet exist in &os;. As + such, the /dev/dtrace/dtrace is strictly + limited to root users only. + + Finally, the DTrace software falls under &sun;'s + CDDL license. The Common Development + and Distribution License comes with &os;, see the + /usr/src/cddl/contrib/opensolaris/OPENSOLARIS.LICENSE + or view it online at + + http://www.opensolaris.org/os/licensing. + + This license means that a &os; kernel with the DTrace options + is still BSD licensed; however the + CDDL kicks in when the modules are distributed + in binary form, or the binaries are loaded. + + + + Enabling DTrace Support + + To enable support for DTrace, add the following lines to + the kernel configuration file: + + options KDTRACE_HOOKS +options DDB_CTF + + + Users of the AMD64 architecture will want to add the + following line to their kernel configuration file: + + options KDTRACE_FRAME + + This option provides support for the FBT + feature. DTrace will work without this option; however, there + will be limited support for function boundary tracing. + + + All sources must be rebuilt and installed with CTF options. + To accomplish this task, rebuild the &os; sources using: + + &prompt.root; cd /usr/src + &prompt.root; make WITH_CTF=1 buildworld + &prompt.root; make WITH_CFT=1 kernel + &prompt.root; make WITH_CFT=1 installworld + &prompt.root; mergemaster -Ui + + The system will need to be restarted. + + After rebooting and allowing the new kernel to be loaded + into memory, support for the Korn shell should be added. This + is needed as the DTrace toolkit has several utilities written + in ksh. Install the + shells/ksh93. It is also + possible to run these tools under + shells/pdksh or + shells/mksh. + + Finally, obtain the current DTrace toolkit. The current + version is available at + + http://www.opensolaris.org/os/community/dtrace/dtracetoolkit/. + There is an install mechanism included; however, installation + is not required to make use of the bundled utilities. + + + + Using DTrace + + Before making use of DTrace functionality, the DTrace device + must exist. To load the device, issue the following + command: + + &prompt.root; kldload dtraceall + + DTrace support should now be available. To view all probes + the administrator may now execute the following command: + + &prompt.root; dtrace -l | more + + All output is passed to the more + utility as it will quickly overflow the screen buffer. At + this point, DTrace should be considered working. It is now + time to review the toolkit. + + The toolkit is a collection of ready-made scripts to run + with DTrace to collect system information. There are scripts + to check open files, memory, CPU usage and + a lot more. Extract the scripts with the following + command: + + &prompt.root; gunzip -c DTraceToolkit* | tar xvf - + + Change into that directory with the cd + and change the execution permissions on all files, designated + as those files with lower case names, to + 755. + + All of these scripts will need modifications to their + contents. The ones which refer to + /usr/bin/ksh need that changed to + /usr/local/bin/ksh, the others which + use /usr/bin/sh need to be altered to use + /bin/sh, and finally the ones which + use /usr/bin/perl will need altered to + use /usr/local/bin/perl. + + + At this point it is prudent to remind the reader that + DTrace support in &os; is incomplete + and experimental. Many of these scripts + will not work as they are either too &solaris;-specific or + use probes which are unsupported at this time. + + + At the time of this writing only two of the scripts of the + DTrace Toolkit are fully supported in &os;: + the hotkernel + and procsystime scripts. These are the two + we will explore in the following parts of this section. + + The hotkernel is designed to identify + which function is using the most kernel time. Run normally, it + will produce output similar to the following: + + &prompt.root; ./hotkernel +localhost# ./hotkernel +Sampling... Hit Ctrl-C to end. + + The system administrator must use the + CtrlC + 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: + + kernel`_thread_lock_flags 2 0.0% +0xc1097063 2 0.0% +kernel`sched_userret 2 0.0% +kernel`kern_select 2 0.0% +kernel`generic_copyin 3 0.0% +kernel`_mtx_assert 3 0.0% +kernel`vm_fault 3 0.0% +kernel`sopoll_generic 3 0.0% +kernel`fixup_filename 4 0.0% +kernel`_isitmyx 4 0.0% +kernel`find_instance 4 0.0% +kernel`_mtx_unlock_flags 5 0.0% +kernel`syscall 5 0.0% +kernel`DELAY 5 0.0% +0xc108a253 6 0.0% +kernel`witness_lock 7 0.0% +kernel`read_aux_data_no_wait 7 0.0% +kernel`Xint0x80_syscall 7 0.0% +kernel`witness_checkorder 7 0.0% +kernel`sse2_pagezero 8 0.0% +kernel`strncmp 9 0.0% +kernel`spinlock_exit 10 0.0% +kernel`_mtx_lock_flags 11 0.0% +kernel`witness_unlock 15 0.0% +kernel`sched_idletd 137 0.3% +0xc10981a5 42139 99.3% + + + + This script will also work with kernel modules. To use this + feature, run the script with the flag: + + &prompt.root; ./hotkernel -m + + localhost# ./hotkernel -m +Sampling... Hit Ctrl-C to end. +^C +MODULE COUNT PCNT +0xc107882e 1 0.0% +0xc10e6aa4 1 0.0% +0xc1076983 1 0.0% +0xc109708a 1 0.0% +0xc1075a5d 1 0.0% +0xc1077325 1 0.0% +0xc108a245 1 0.0% +0xc107730d 1 0.0% +0xc1097063 2 0.0% +0xc108a253 73 0.0% +kernel 874 0.4% +0xc10981a5 213781 99.6% + + + + The procsystime script captures and + prints the system call time usage for a given + PID or process name. In the following + example, a new instance of /bin/csh + was spawned. The 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: + + &prompt.root; ./procsystime -n csh +Tracing... Hit Ctrl-C to end... +^C + +Elapsed Times for processes csh, + + SYSCALL TIME (ns) + getpid 6131 + sigreturn 8121 + close 19127 + fcntl 19959 + dup 26955 + setpgid 28070 + stat 31899 + setitimer 40938 + wait4 62717 + sigaction 67372 + sigprocmask 119091 + gettimeofday 183710 + write 263242 + execve 492547 + ioctl 770073 + vfork 3258923 + sigsuspend 6985124 + read 3988049784 + + As shown, the read system call seems to use the + most time in nanoseconds with the getpid() + system call used the least amount of time. + + + + The D Language + + The DTrace Toolkit includes many scripts in the special language of + DTrace. This language is called the D language by &sun; + documentation, and it is very similar to C++. An in depth + discussion of the language is beyond the scope of this document. It is + extensively discussed + at . + + + +