tried improving Installation, also trying out new chapter on advanced scripts (tentative)

7 files changed, 164 insertions, 24 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml b/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml
index f7f8ea1d..dbeb3c08 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml
@@ -2,12 +2,14 @@
 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 ]>
 
-<appendix id="SystemTap_Beginners_Guide-Revision_History">
-	<appendixinfo>
+<appendix id="SystemTap_Beginners_Guide-appendix-advancedscripts">
+<!--	<appendixinfo>
 		<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-	</appendixinfo>
-	<title>Revision History</title>
+	</appendixinfo>-->
+	<title>Full Version of Advanced Scripts</title>
 	<para>
+		This appendix contains the full versions of all scripts discussed in <xref linkend="useful-advanced-scripts"/>.
 	</para>
+
 </appendix>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
index cc451ec4..f428f5e5 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
@@ -128,14 +128,14 @@ enabled=1
 <para><command>staprun <replaceable>instrumentation</replaceable></command></para>
 
 <para>
-	For example, to create the <emphasis>instrumentation module</emphasis> <filename>module.ko</filename> from the SystemTap script <filename>script.stp</filename> for the <emphasis>target kernel</emphasis> 2.6.25.9-76.fc9 (on i686 architecture), use the following command:
+	For example, to create the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename> from the SystemTap script <xref linkend="simplesimplescript"/> (from <xref linkend="installproper"/>) for the <emphasis>target kernel</emphasis> 2.6.25.9-76.fc9 (on i686 architecture), use the following command:
 </para>
 
-<para><command>stap -r 2.6.25.9-76.fc9.x86_64 script.stp -m module</command></para>
+<para><command>stap -r 2.6.25.9-76.fc9.x86_64 simple.stp -m module</command></para>
 
-<para>This will create a module named <filename>module.ko</filename>. To use the <emphasis>instrumentation module</emphasis> <filename>module.ko</filename>, copy it to the <emphasis>target system</emphasis> and run the following command (on the <emphasis>target system</emphasis>):</para>
+<para>This will create a module named <filename>simple.ko</filename>. To use the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename>, copy it to the <emphasis>target system</emphasis> and run the following command (on the <emphasis>target system</emphasis>):</para>
 
-<para><command>staprun module.ko</command></para>
+<para><command>staprun simple.ko</command></para>
 	
 <!--<procedure id="preppingxcompile">
 	<title>Preparing for a Cross-Compile</title>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index 0ccefa3a..8670db59 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -14,8 +14,18 @@
 		</remark>	
 		
 		<para>
-			To deploy SystemTap, you need to install the SystemTap packages along with the corresponding set of <filename>-devel</filename> and <filename>-debuginfo</filename> packages for your kernel. This means that if your system has multiple kernels installed, and you wish to use SystemTap on more than one kernel kernel, you will need to install the <filename>-devel</filename> and <filename>-debuginfo</filename> packages for <emphasis>each</emphasis> of those kernel versions.
+			To deploy SystemTap, you need to install the SystemTap packages along with the corresponding set of <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages for your kernel. This means that if your system has multiple kernels installed, and you wish to use SystemTap on more than one kernel kernel, you will need to install the <filename>-devel</filename> and <filename>-debuginfo</filename> packages for <emphasis>each</emphasis> of those kernel versions.
 		</para>
+		
+		<para>
+			These procedures will be discussed in detail in the following sections.
+		</para>	
+		
+	<important>
+		<title>Important</title>
+		<para>Many users confuse <filename>-debuginfo</filename> with <filename>-debug</filename>. Remember that the deployment of SystemTap requires the installation of the <filename>-debuginfo</filename> version of the kernel, not the <filename>-debug</filename> version.</para>
+	</important>	
+		
 <section id="installprep">
 	<title>Preparing For Installation</title>
 		<para>
@@ -35,7 +45,7 @@ uname -r
 		</para>-->
 		
 		<para>
-			Most <filename>-debuginfo</filename> packages for Red Hat Enterprise Linux 5 can be found at the following link (under <filename><replaceable>arch</replaceable>/Debuginfo</filename>, where <filename>arch</filename> is the appropriate architecture for your system:
+			Most <filename>-debuginfo</filename> packages for Red Hat Enterprise Linux 5 can be found at the following link (under <filename><replaceable>arch</replaceable>/Debuginfo</filename>, where <filename><replaceable>arch</replaceable></filename> is the appropriate architecture for your system:
 		</para>
 		
 		<para><ulink url="ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/">ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/</ulink></para>
@@ -57,7 +67,25 @@ uname -r
 		<listitem><para><filename>systemtap-runtime</filename></para></listitem>
 	</itemizedlist>
 	
-	<para>This will install the SystemTap suite of tools.</para> 
+	<para>To do so, run <command>yum install systemtap systemtap-runtime</command>; this will work if your <application>yum</application> repository is configured accordingly. To configure <application>yum</application>, simply add the following file to <filename>/etc/yum.repos.d</filename>:</para>
+	
+<formalpara id="sampleyum">
+	<title>packages.repo</title>
+<para>
+<screen>
+[packages]
+name=Packages for OS
+baseurl=<replaceable>repository</replaceable> 
+enabled=1
+gpgcheck=0
+</screen>
+</para>	
+</formalpara>		
+
+<para>
+	In <xref linkend="sampleyum"/>, <replaceable>repository</replaceable> is the full URL of the repository containing the packages you wish to install. The <computeroutput>name=</computeroutput> parameter, along with the title (<computeroutput>[packages]</computeroutput>) and filename, can be set arbitrarily, as long as you use the <filename>.repo</filename> filename extension.
+</para>
+	 
 <!-- </step> -->
 <!--<procedure id="deployproper">
 	<title>Deploying SystemTap</title>
@@ -81,7 +109,59 @@ uname -r
 	<listitem><para><filename>kernel-debuginfo-common-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem>
 	<listitem><para><filename>kernel-devel-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem>
 </itemizedlist>
+
+<para>
+As mentioned earlier in <xref linkend="using-setup"/>, <filename>kernel-debuginfo</filename> should not be confused with <filename>kernel-debug</filename>. Thus, in this example, you do not need to install the <filename>kernel-debug-2.6.18-53.1.13.el5.i686.rpm</filename> package. 
+</para>
 </example>
+
+<important>
+	<title>Important</title>
+	
+	<para>The version of the <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>.</para>
+</important>
+<para>
+	You can download the necessary packages via your web browser. Once you have downloaded the packages, install them by running <command>rpm -ivh <replaceable>package names</replaceable></command>.
+</para>
+	
+	
+<para>	
+	Alternatively, if the packages are in a <command>yum</command> repository, you can configure <command>yum</command> again to download and install directly from that repository. Once you've configured <command>yum</command> correctly, run <command>yum install <replaceable>full package names</replaceable></command> (as root).
+</para>
+	
+
+<formalpara id="initialtest">
+	<title>Initial Testing</title>
+	
+<para>If you are currently using the kernel you wish to probe with SystemTap, you can immediately test whether the deployment was successful. If not, you will need to reboot and load the appropriate kernel.</para>
+</formalpara>
+
+<para>To start the test, create the following SystemTap script (ensure that you are using the filename extension <filename>.stp</filename>):</para>
+
+<formalpara id="simplesimplescript">
+	<title>simple.stp</title>
+<para>
+<programlisting>
+probe timer.s(2) {exit()}

+</programlisting>
+</para>
+</formalpara>
+
+<para><xref linkend="simplesimplescript"/> is a SystemTap script that simply closes after 2 seconds. To run the test, use <command>stap -v simple.stp</command>. If the SystemTap deployment was successful, you should get the following verbose output:</para>
+
+<screen>
+Pass 1: parsed user script and 55 library script(s) in 340usr/0sys/356real ms.

+Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 10usr/10sys/7real ms.

+Pass 3: translated to C into "/tmp/stapwPJf4N/stap_166903963eb5e3849b44f0ba89d442a8_252.c" in 0usr/0sys/1real ms.

+Pass 4: compiled C into "stap_166903963eb5e3849b44f0ba89d442a8_252.ko" in 2050usr/230sys/2274real ms.

+Pass 5: starting run.

+Pass 5: run completed in 30usr/220sys/2260real ms.

+</screen>
+
+<para>
+	The last two lines of the output (i.e. beginning with <computeroutput>Pass 5</computeroutput> indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, and close it with no errors.
+</para>	
+
 <!--</step>
 </section>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
index 28abf439..67547bd8 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
@@ -9,28 +9,29 @@
 	</para>
 	
 	<para>
-		For system administrators, SystemTap can be used as a performance monitoring tool for &PROD;. It is most useful when other similar tools cannot precisely pinpoint a bottleneck in the system, requiring a deep analysis of kernel activity. In the same manner, application developers can also use SystemTap to monitor, in finer detail, how their application behaves.
+		For system administrators, SystemTap can be used as a performance monitoring tool for &PROD;. It is most useful when other similar tools cannot precisely pinpoint a bottleneck in the system, requiring a deep analysis of kernel activity. In the same manner, application developers can also use SystemTap to monitor, in finer detail, how their application behaves within the Linux system.
 	</para>
-	  
+	
+	
 <!--	
 	<para>
 		SystemTap was developed as a Linux version of the DTrace tool (for <trademark>Sun Solaris</trademark>).
 	</para>	
 	-->
 <section id="goals">
-	<title>Goals</title>
-	<para>SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist in identifying the underlying cause of a performance or functional problem.</para>
+	<title>Documentation Goals</title>
+	<para>SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a performance or functional problem.</para>
 	
-	<para>Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running its suite of tools against specific <firstterm>tapsets</firstterm> or SystemTap scripts.</para> 
+	<para>Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running user-written SystemTap scripts.</para> 
 		
-	<para>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As such, much of the existing documentation for SystemTap is primarily for advanced users. This could present a steep learning curve for administrators or developers whose knowledge of the Linux kernel is little to none.</para>
+	<para>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As such, much of the existing documentation for SystemTap is primarily for advanced users. This could present a steep learning curve for administrators or developers with limited knowledge of and experience with the Linux kernel.</para>
 	
 	<para>In line with that, the main goals of the <citetitle>SystemTap Beginner's Guide</citetitle> are as follows:</para>
 	
 	<itemizedlist>
 		<listitem><para>To introduce users to SystemTap, familiarize them with its architecture, and provide setup instructions for all kernel types.</para></listitem>
 		
-		<listitem><para>To provide pre-written SystemTap scripts for monitoring detailed activity in different components of the system, along with instructions on how to analyze their output.</para></listitem>  
+		<listitem><para>To provide pre-written SystemTap scripts for monitoring detailed activity in different components of the system, along with instructions on how to run them and analyze their output.</para></listitem>  
 	</itemizedlist>	
 <!-- </formalpara>	 -->
 <remark>above,  Short description on the underlying goals of SystemTap_Beginners_Guide, what we want to teach users.</remark>
@@ -45,20 +46,47 @@
 	</section>
 	-->
 	<section id="intro-systemtap-vs-others">
-		<title>SystemTap Versus Other Monitoring Tools</title>
+<!-- 		<title>SystemTap Versus Other Monitoring Tools</title> -->
+		<title>SystemTap Capabilities</title>
 		<remark>
 			** Short summary; when is SystemTap suitable vs other popular monitoring tools (e.g. top, Oprofile, /proc)
 		</remark>
 		
+	<para>SystemTap was originally developed as a working Linux version of <firstterm>Dtrace</firstterm>. Dtrace is a Sun Microsystems "dynamic tracing" framework that assists administrators in monitoring  and troubleshooting kernel and user-space applications in real time.</para>
+	
+	<para>SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity. In addition, SystemTap combines this capability with two things:</para>
+	
+<itemizedlist>
+	<listitem><para>Flexibility: SystemTap's framework allows users to develop simple scripts for investigating and monitoring a wide variety of kernel functions, system calls, and other events that occur in kernel-space. With this, SystemTap is not soo much a <emphasis>tool</emphasis> as it is a system that allows you to develop your own kernel-specific forensic and monitoring tools.</para></listitem>
+	
+	<listitem><para>Ease-Of-Use: as mentioned earlier, SystemTap allows users to probe kernel-space events without having to resort to instrument, recompile, install, and reboot the kernel.</para></listitem>
+</itemizedlist>
+
+<para>Most of the SystemTap scripts enumerated in <xref linkend="useful-systemtap-scripts"/> demonstrate system forensics and monitoring capabilities not natively available with other similar tools (such as <command>top</command>, <command>oprofile</command>, or <command>ps</command>). These scripts are provided to give readers extensive examples of the application of SystemTap, which in turn will educate them further on the capabilities they can employ when writing their own SystemTap scripts.</para> 
+<!--
+<example id="introstory">
+	<title>A Simple SystemTap Case Study</title>
+<para>The entire system is running slow. You suspect that this could be caused by a process (or multiple processes) performing an excessive amount of reads or writes to disk.</para>
+
+<para>To test your theory, you write a simple SystemTap script that tracks how many reads and writes the system did in a 5-second time period. Once you prove your theory right, you then write another SystemTap script that tracks which processes are performing excessive reads/writes.</para>
+
+<para>With a list of processes performing excessive reads/writes, you can then examine which ones are generating more I/O activity than expected.</para>
+
+-->
+
+
+<!--					
 <formalpara>
 	<title>Advantages</title>
 	<para>TBD</para>
 </formalpara>
-
+-->
 <formalpara>
 	<title>Limitations</title>
-	<para>TBD</para>
-</formalpara>	
+	<para>The current iteration of SystemTap allows for a multitude of options when probing kernel-space events. However, SystemTap's ability to probe user-space events is quite limited. At present, the developmental efforts of the SystemTap community are geared towards improving SystemTap's user-space probing capabilities.</para>
+</formalpara>
+
+
 	</section>
 
 </chapter>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml
index ccc97915..b69e00df 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml
@@ -10,6 +10,7 @@
 	<!--<xi:include href="Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
 	<xi:include href="Understanding_How_SystemTap_Works.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_SystemTap_Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!-- 	<xi:include href="Useful_Advanced_Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
 	<xi:include href="Errors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Tips_Tricks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="References.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -18,7 +19,6 @@
 	-->
 		
 <!-- 	<xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
-	
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/>
 </book>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml
new file mode 100644
index 00000000..71aaad9b
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml
@@ -0,0 +1,30 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter id="useful-advanced-scripts">
+	<title>Useful SystemTap Scripts</title>
+	
+	<para>This chapter contains several advanced applications of SystemTap. The scripts enumerated herein combine SystemTap scripts with other tools in order to address some complex administrative tasks. All of these scripts are available at the following link:</para>
+	
+	<para><ulink url="http://sourceware.org/systemtap/wiki/WarStories?action=fullsearch&amp;context=180&amp;value=traceio2&amp;titlesearch=Titles">http://sourceware.org/systemtap/wiki/WarStories?action=fullsearch&amp;context=180&amp;value=traceio2&amp;titlesearch=Titles</ulink></para>
+		
+	<para>Due to the relative length of the scripts discussed in this chapter, the full version of each script is documented in <xref linkend="SystemTap_Beginners_Guide-appendix-advancedscripts"/>.</para>
+	
+	<remark>this chapter will feature the following scripts:</remark>
+	
+	<remark>http://sourceware.org/systemtap/wiki/WSPSTimeouts?highlight=((WarStories))</remark>
+	
+	<remark>http://sourceware.org/systemtap/wiki/WSPfiles?highlight=((WarStories))</remark>
+	
+	<remark>http://sourceware.org/systemtap/wiki/WSPSTimeouts?highlight=%28%28WarStories%29%29</remark>
+	
+	<remark>WAIT http://sourceware.org/systemtap/wiki/WSPanicOnOom?highlight=((WarStories))</remark>
+	
+	<remark>http://sourceware.org/systemtap/wiki/WSPfiles?highlight=((WarStories))</remark>
+	
+
+	
+	
+</chapter>
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
index d56cbfc1..b1d3f846 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
@@ -4,7 +4,7 @@
 
 
 	<section id="nettopsect">
-		<title>Kernel Profiling</title>
+		<title>Network Profiling</title>
 		
 		
 <remark>