added sections to Useful Scripts (graphs, disktop)

5 files changed, 155 insertions, 82 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml b/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
index c19ae8f0..676af712 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
@@ -6,7 +6,7 @@
 	<corpauthor>Red Hat Enterprise Linux Documentation</corpauthor>
 	<author>
 		<firstname>Don</firstname>
-		<surname>Domingo</surname>
+		<surname>Domingo </surname>
 		<affiliation>
 			<orgname>Engineering Services and Operations</orgname>
 			<orgdiv>Content Services</orgdiv>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-Disk.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-Disk.xml
index a5df51b6..a7c16b25 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-Disk.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-Disk.xml
@@ -3,8 +3,9 @@
 ]>
 
 
-	<section id="useful-disk">
-		<title>Disk</title>
+	<section id="useful-disk-graphwithgnuplot">
+		<title>Real-Time Graphing of Disk and CPU Utilization</title>
+		
 		<remark>
 			http://sourceware.org/systemtap/examples/subsystem-index.html
 		</remark>
@@ -12,10 +13,127 @@
 		<remark>
 			Graphing Disk and CPU Utilization - http://sourceware.org/systemtap/examples/general/graphs.stp 
 		</remark>	
+
+	<para>This section describes how you can graph disk and CPU utilization in real-time, i.e. in samples of 1 second each.</para>
+	
+<formalpara id="scriptdiskusage">
+		<title>disk-usage-graph.stp</title>
+<para>
+<programlisting>
+#! stap
+# disk I/O stats
+probe begin { qnames["ioblock"] ++; qsq_start ("ioblock") }
+probe ioblock.request { qs_wait ("ioblock") qs_run("ioblock") }
+probe ioblock.end { qs_done ("ioblock") }
+# CPU utilization
+probe begin { qnames["cpu"] ++; qsq_start ("cpu") }
+probe scheduler.cpu_on { if (!idle) {qs_wait ("cpu") qs_run ("cpu") }}
+probe scheduler.cpu_off { if (!idle) qs_done ("cpu") }
+# ------------------------------------------------------------------------
+# utilization history tracking
+global N
+probe begin { N = 50 }
+global qnames, util, histidx
+function qsq_util_reset(q) {
+  u=qsq_utilization (q, 100)
+  qsq_start (q)
+  return u
+}
+probe timer.ms(100) {  # collect utilization percentages frequently
+  histidx = (histidx + 1) % N  # into circular buffer
+  foreach (q in qnames)
+    util[histidx,q] = qsq_util_reset(q)
+}
+# ------------------------------------------------------------------------
+# general gnuplot graphical report generation
+probe timer.ms(1000) {
+  # emit gnuplot command to display recent history
+  printf ("set yrange [0:100]\n")
+  printf ("plot ")
+  foreach (q in qnames+)
+    {
+      if (++nq >= 2) printf (", ")
+      printf ("'-' title \"%s\" with lines", q)
+    }
+  printf ("\n")
+  foreach (q in qnames+) {
+    for (i = (histidx + 1) % N; i != histidx; i = (i + 1) % N)
+      printf("%d\n", util[i,q])
+    printf ("e\n")
+  }
+  printf ("pause 1\n")
+}
+</programlisting>
+</para>
+</formalpara>		
+
+<para><xref linkend="scriptdiskusage"/> outputs raw statistics on both CPU and disk usage per second. I/O usage is tracked through the events <command>ioblock.request</command> and <command>ioblock.request.end</command>, which track each request (and request completion) for a generic block I/O. CPU usage is tracked through <command>scheduler.cpu_on</command> and <command>scheduler.cpu_off</command>, which are activated whenever a process begins (and ends) a command execution on a CPU.</para>
+	
+<section id="gnuplotexplain">
+	<title>gnuplot</title>
+<para>Running <xref linkend="scriptdiskusage"/> by itself hardly presents any data that is useful, as in <xref linkend="rawdiskusagegraph"/>.</para>
+
+<example id="rawdiskusagegraph"><title>Raw disk-usage-graph.stp Output</title>
+<screen>
+[...]	
+62

+5

+3

+4

+6

+4

+4

+5

+5

+3

+6

+5

+e

+pause 1

+</screen>
+</example>
+
+<para>However, refining the output of <xref linkend="scriptdiskusage"/> through <command>gnuplot</command> presents us with a more useful result. <command>gnuplot</command> is a lightweight, command-line driven plotting program that helps you display data in a graphical format.</para>
+
+<para>By piping <xref linkend="scriptdiskusage"/> output to <command>gnuplot</command> (as in <command>stap disk-usage-gr<remark>
+			http://sourceware.org/systemtap/examples/subsystem-index.html
+		</remark>
 		
 		<remark>
+			Graphing Disk and CPU Utilization - http://sourceware.org/systemtap/examples/general/graphs.stp 
+		</remark>	aph.stp | gnuplot</command>), we get a graphical output similar to the following:</para>
+
+<figure id="gnuoutputsample">
+	<title>Graphical Output Sample</title>
+<mediaobject>
+	<imageobject>
+		<imagedata fileref="images/gnuplotsample.png" format="PNG"/>
+	</imageobject>
+	<textobject>
+		<phrase>Sample output</phrase>
+	</textobject>
+	<caption>
+		<para>
+			Sample output of <xref linkend="scriptdiskusage"/> when piped through <command>gnuplot</command>
+		</para>
+	</caption>
+</mediaobject>
+</figure>
+
+<para><xref linkend="gnuoutputsample"/> presents a cleaner, more useful graphical output. This graph can show you the level of utilization for both I/O and CPU, in real time.</para>
+
+<remark>
+	question: does this script also capture stap process? i.e. does the graph also include CPU utilization by systemtap while the script is running?
+</remark>	
+
+
+		
+<!--	
+	disktop has no entry in war stories
+		<remark>
 			Summarize Disk Read/Write Traffic
 			http://sourceware.org/systemtap/examples/io/disktop.stp
-		</remark>	
+		</remark>-->
+	</section>		
 	</section>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
index df6477de..a3e3d8a7 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
@@ -130,83 +130,6 @@ UID      PID     PPID                       CMD   DEVICE    T        BYTES
 </screen>
 </example>
 
-<para>
-
-
-
-
-
-
-
-
-
-<para><xref linkend="scriptdiskusage"/> outputs raw statistics on both CPU and disk usage per second. I/O usage is tracked through the events <command>ioblock.request</command> and <command>ioblock.request.end</command>, which track each request (and request completion) for a generic block I/O. CPU usage is tracked through <command>scheduler.cpu_on</command> and <command>scheduler.cpu_off</command>, which are activated whenever a process begins (and ends) a command execution on a CPU.</para>
-	
-<section id="gnuplotexplain">
-	<title>gnuplot</title>
-<para>Running <xref linkend="scriptdiskusage"/> by itself hardly presents any data that is useful, as in <xref linkend="rawdiskusagegraph"/>.</para>
-
-<example id="rawdiskusagegraph"><title>Raw disk-usage-graph.stp Output</title>
-<screen>
-[...]	
-62
-5
-3
-4
-6
-4
-4
-5
-5
-3
-6
-5
-e
-pause 1
-</screen>
-</example>
 
-<para>However, refining the output of <xref linkend="scriptdiskusage"/> through <command>gnuplot</command> presents us with a more useful result. <command>gnuplot</command> is a lightweight, command-line driven plotting program that helps you display data in a graphical format.</para>
-
-<para>By piping <xref linkend="scriptdiskusage"/> output to <command>gnuplot</command> (as in <command>stap disk-usage-graph.stp | gnuplot</command>), we get a graphical output similar to the following:</para>
-
-<figure id="gnuoutputsample">
-	<title>Graphical Output Sample</title>
-<mediaobject>
-	<imageobject>
-		<imagedata fileref="images/gnuplotsample.png" format="PNG"/>
-	</imageobject>
-	<textobject>
-		<phrase>Sample output</phrase>
-	</textobject>
-	<caption>
-		<para>
-			Sample output of <xref linkend="scriptdiskusage"/> when piped through <command>gnuplot</command>
-		</para>
-	</caption>
-</mediaobject>
-</figure>
-
-<para><xref linkend="gnuoutputsample"/> presents a cleaner, more useful graphical output. This graph can show you the level of utilization for both I/O and CPU, in real time.</para>
-
-<remark>
-	question: does this script also capture stap process? i.e. does the graph also include CPU utilization by systemtap while the script is running?
-</remark>	
-
-
-		<remark>
-			http://sourceware.org/systemtap/examples/subsystem-index.html
-		</remark>
-		
-		<remark>
-			Graphing Disk and CPU Utilization - http://sourceware.org/systemtap/examples/general/graphs.stp 
-		</remark>	
-	
-	
-		<remark>
-			Summarize Disk Read/Write Traffic
-			http://sourceware.org/systemtap/examples/io/disktop.stp
-		</remark>
-	</section>		
 	</section>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
index d3cfb897..51fef276 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -4,6 +4,12 @@
 
 <chapter id="useful-systemtap-scripts">
 	<title>Useful SystemTap Scripts</title>
+	
+	<para>This chapter enumerates several SystemTap scripts you can use to monitor and investigate different subsystems. All of these scripts are available at the following link:</para>
+	
+	<para><ulink url="http://sourceware.org/systemtap/examples/subsystem-index.html">http://sourceware.org/systemtap/examples/subsystem-index.html</ulink></para>
+		
+		
 	<remark>
 		short intro, reference to online source (http://sourceware.org/systemtap/examples/subsystem-index.html); "always updated"
 	</remark>
@@ -13,6 +19,7 @@
 	<remark>case studies and more info on some scripts here - http://sourceware.org/systemtap/wiki/WarStories</remark>
 	
 	<xi:include href="Useful_Scripts-Disk.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-disktop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-IO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Kernel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index 30c8500f..01e30fc7 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -43,7 +43,7 @@ uname -r
 			You will also need to configure <command>yum</command> to point to a repository that houses the necessary debug RPMs. One such repository is:
 		</para>
 		
-		<para><ulink url="	ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/"/></para>
+		<para><ulink url="ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/">ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/</ulink></para>
 		
 		<remark>find any other such repository, if only for RHEL</remark>	
 			
@@ -146,6 +146,13 @@ uname -r
 	</listitem>	
 </varlistentry>	
 
+<varlistentry>
+	<term>-e "<replaceable>[script]</replaceable></term>
+	<listitem>
+		<para>Run given <command><replaceable>[script]</replaceable></command>.</para>
+	</listitem>
+</varlistentry>
+
 <!--	
 <varlistentry>
 	<term></term>
@@ -156,12 +163,30 @@ uname -r
 			-->
 </variablelist>
 
+<para>You can also instruct <command>stap</command> to run scripts from standard input using the switch <command>-</command>. To illustrate:</para>
+
+<example id="stdinstap">
+	<title>Running Scripts From Standard Input</title>
+<programlisting>
+echo "probe timer.s(1) {exit()}" | stap -
+</programlisting>
+</example>
+
+<para><xref linkend="stdinstap"/> instructs <command>stap</command> to run the script passed by <command>echo</command> to standard input. Any <command>stap</command> options you wish to use should be inserted before the <command>-</command> switch; for instance, to make the example in <xref linkend="stdinstap"/> more verbose, the command would be:</para>
+
+<para><command>echo "probe timer.s(1) {exit()}" | stap -v -</command></para>
+
 <remark>any other useful options worth noting here for beginners?</remark>
 
 <para>For more information about <command>stap</command>, refer to <command>man stap</command>.</para>
 
 <para>To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use <command>staprun</command> instead. For more information about <command>staprun</command> and cross-instrumentation, refer to <xref linkend="cross-compiling"/>.</para>
 
+<note>
+	<title>Note</title>
+	<para>The <command>stap</command> options <command>-v</command> and <command>-o</command> also work for <command>staprun</command>. For more information about <command>staprun</command>, refer to <command>man staprun</command>.</para>
+</note>	
+
 	</section>
 
 </chapter>