Date: Wed, 16 Apr 2014 14:01:56 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> 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 Message-ID: <201404161401.s3GE1uRk050937@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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</programlisting> <sect1 xml:id="dtrace-using"> <title>Using &dtrace;</title> + <para>&dtrace; scripts consist of a list of one or more + <firstterm>probes</firstterm>, 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.</para> + <para>To view all probes, the administrator can execute the following command:</para> <screen>&prompt.root; <userinput>dtrace -l | more</userinput></screen> - <para>This section demonstrates how to use two of the fully supported scripts from the + <para>Each probe has an <literal>ID</literal>, a + <literal>PROVIDER</literal> (dtrace or fbt), a + <literal>MODULE</literal>, and a + <literal>FUNCTION NAME</literal>. Refer to &man.dtrace.1; for + more information about this command.</para> + + <para>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</filename> and <filename>procsystime</filename> scripts.</para> <para>The <filename>hotkernel</filename> 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:</para> <screen>&prompt.root; <userinput>cd /usr/share/dtrace/toolkit</userinput> &prompt.root; <userinput>./hotkernel</userinput> Sampling... Hit Ctrl-C to end.</screen> - <para>The system administrator must use the + <para>As instructed, use the <keycombo action="simul"><keycap>Ctrl</keycap><keycap>C</keycap> </keycombo> 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. --> <para>This script will also work with kernel modules. To use this - feature, run the script with the <option>-m</option> - flag:</para> + feature, run the script with <option>-m</option>:</para> <screen>&prompt.root; <userinput>./hotkernel -m</userinput> Sampling... Hit Ctrl-C to end. @@ -297,10 +314,10 @@ kernel seriously obvious. It is 5AM btw. --> <para>The <filename>procsystime</filename> script captures and - prints the system call time usage for a given - <acronym>PID</acronym> or process name. In the following + prints the system call time usage for a given process <acronym>ID</acronym> + (<acronym>PID</acronym>) or process name. In the following example, a new instance of <filename>/bin/csh</filename> was - spawned. The <filename>procsystime</filename> was executed and + spawned. Then, <filename>procsystime</filename> was executed and remained waiting while a few commands were typed on the other incarnation of <command>csh</command>. These are the results of this test:</para> @@ -331,8 +348,8 @@ Elapsed Times for processes csh, sigsuspend 6985124 read 3988049784</screen> - <para>As shown, the <function>read()</function> system call seems - to use the most time in nanoseconds with the + <para>As shown, the <function>read()</function> system call + used the most time in nanoseconds while the <function>getpid()</function> system call used the least amount of time.</para> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404161401.s3GE1uRk050937>