From owner-svn-doc-head@FreeBSD.ORG Wed Apr 16 14:01:56 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 4C012CD9; Wed, 16 Apr 2014 14:01:56 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 38C98136C; Wed, 16 Apr 2014 14:01:56 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3GE1ull050938; Wed, 16 Apr 2014 14:01:56 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3GE1uRk050937; Wed, 16 Apr 2014 14:01:56 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404161401.s3GE1uRk050937@svn.freebsd.org> From: Dru Lavigne Date: Wed, 16 Apr 2014 14:01:56 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44576 - head/en_US.ISO8859-1/books/handbook/dtrace X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 16 Apr 2014 14:01:56 -0000 Author: dru Date: Wed Apr 16 14:01:55 2014 New Revision: 44576 URL: http://svnweb.freebsd.org/changeset/doc/44576 Log: Finish editorial review of DTrace chapter. Add an explanatory paragraph for probes. This chapter still needs a section on userland DTrace. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml Wed Apr 16 13:08:13 2014 (r44575) +++ head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml Wed Apr 16 14:01:55 2014 (r44576) @@ -215,25 +215,43 @@ options DEBUG=-g Using &dtrace; + &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. + To view all probes, the administrator can execute the following command: &prompt.root; dtrace -l | more - This section demonstrates how to use two of the fully supported scripts from the + Each probe has an ID, a + PROVIDER (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 hotkernel and procsystime scripts. The hotkernel script is designed to identify - which function is using the most kernel time. Run normally, it + which function is using the most kernel time. It will produce output similar to the following: &prompt.root; cd /usr/share/dtrace/toolkit &prompt.root; ./hotkernel Sampling... Hit Ctrl-C to end. - The system administrator must use the + As instructed, use the CtrlC key combination to stop the process. Upon termination, the script will display a list of kernel functions @@ -272,8 +290,7 @@ kernel`sched_idletd how we should look that up. --> This script will also work with kernel modules. To use this - feature, run the script with the - flag: + feature, run the script with : &prompt.root; ./hotkernel -m Sampling... Hit Ctrl-C to end. @@ -297,10 +314,10 @@ kernel seriously obvious. It is 5AM btw. --> The procsystime script captures and - prints the system call time usage for a given - PID or process name. In the following + prints the system call time usage for a given process ID + (PID) or process name. In the following example, a new instance of /bin/csh was - spawned. The procsystime was executed and + spawned. Then, 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: @@ -331,8 +348,8 @@ Elapsed Times for processes csh, sigsuspend 6985124 read 3988049784 - As shown, the read() system call seems - to use the most time in nanoseconds with the + As shown, the read() system call + used the most time in nanoseconds while the getpid() system call used the least amount of time.