svn commit: r44571 - head/en_US.ISO8859-1/books/handbook/dtrace

[Dru Lavigne]

Author: dru
Date: Tue Apr 15 23:00:32 2014
New Revision: 44571
URL: http://svnweb.freebsd.org/changeset/doc/44571

Log:
  Add needed kernel option which addresses PR150255.
  Clarify the Toolkit and what comes by default in 10.0.
  Fix a grammo.
  The Using DTrace section still needs an editorial review.
  
  Submitted by:	markj
  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	Tue Apr 15 22:06:48 2014	(r44570)
+++ head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml	Tue Apr 15 23:00:32 2014	(r44571)
@@ -162,7 +162,8 @@ that might make this chapter too large.
 	linkend="kernelconfig"/>:</para>
 
     <programlisting>options         KDTRACE_HOOKS
-options         DDB_CTF</programlisting>
+options         DDB_CTF
+options		DEBUG=-g</programlisting>
 
     <para>Users of the AMD64 architecture should also add this
       line:</para>
@@ -175,21 +176,34 @@ options         DDB_CTF</programlisting>
 
     <para>Once the &os; system has rebooted into the new kernel, or
       the &dtrace; kernel modules have been loaded using
-      <command>kldload dtraceall</command>, the system will have
-      support for the Korn shell.  This is needed as the &dtrace;
+      <command>kldload dtraceall</command>, the system will need
+      support for the Korn shell as the &dtrace;
       Toolkit has several utilities written in <command>ksh</command>.
       Make sure that the <package>shells/ksh93</package> package or
       port is installed.  It is also possible to run these tools under
       <package>shells/pdksh</package> or
       <package>shells/mksh</package>.</para>
 
-    <para>Finally, obtain the current &dtrace; Toolkit.  FreeBSD 10
-      includes the &dtrace; Toolkit in
-      <filename>/usr/share/dtrace</filename>.  Otherwise, install the
-      &dtrace; Toolkit using the
+    <para>Finally, install the current &dtrace; Toolkit,
+      a collection of ready-made scripts
+      for collecting system information.  There are scripts to check
+      open files, memory, <acronym>CPU</acronym> usage, and a lot
+      more.  &os; 10
+      installs a few of these scripts into
+      <filename>/usr/share/dtrace</filename>.  On other &os; versions,
+      or to install the full
+      &dtrace; Toolkit, use the
       <package>sysutils/DTraceToolkit</package> package or
       port.</para>
 
+    <note>
+      <para>The scripts found in
+	<filename>/usr/share/dtrace</filename> have been specifically
+	ported to &os;.  Not all of the scripts found in the &dtrace;
+	Toolkit will work as-is on &os; and some scripts may require
+	some effort in order for them to work on &os;.</para>
+    </note>
+
     <para>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
@@ -206,34 +220,12 @@ options         DDB_CTF</programlisting>
 
     <screen>&prompt.root; <userinput>dtrace -l | more</userinput></screen>
 
-    <para>The &dtrace; Toolkit is a collection of ready-made scripts
-      for collecting system information.  There are scripts to check
-      open files, memory, <acronym>CPU</acronym> usage, and a lot
-      more.  Extract the scripts with the following command:</para>
-
-    <screen>&prompt.root; <userinput>gunzip -c DTraceToolkit* | tar xvf -</userinput></screen>
-
-    <para>Change into that directory with the <command>cd</command>
-      and change the execution permissions on all files, designated as
-      those files with lower case names, to
-      <literal>755</literal>.</para>
-
-    <para>All of these scripts will need modifications to their
-      contents.  The ones which refer to
-      <filename>/usr/bin/ksh</filename> need that changed to
-      <filename>/usr/local/bin/ksh</filename>, the others which use
-      <filename>/usr/bin/sh</filename> need to be altered to use
-      <filename>/bin/sh</filename>, and finally the ones which use
-      <filename>/usr/bin/perl</filename> will need altered to use
-      <filename>/usr/local/bin/perl</filename>.</para>
-
-    <para>At the time of this writing only two of the scripts of the
-      &dtrace; Toolkit are fully supported in &os;: the
+    <para>This section demonstrates how to use two of the fully supported scripts from the
+      &dtrace; Toolkit: the
       <filename>hotkernel</filename> and
-      <filename>procsystime</filename> scripts.  These are the two
-      we will explore in the following parts of this section.</para>
+      <filename>procsystime</filename> scripts.</para>
 
-    <para>The <filename>hotkernel</filename> is designed to identify
+    <para>The <filename>hotkernel</filename> script is designed to identify
       which function is using the most kernel time.  Run normally, it
       will produce output similar to the following:</para>