From 098339421820a5c349a7c1d09b531b7fdcd66302 Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Thu, 11 Sep 2008 16:15:10 +1000
Subject: added remarks

---
 doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index d61ec1cf..d11eec2d 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -114,6 +114,8 @@ probe kernel.function("*@net/socket.c").return { }
 	SystemTap supports the use of a large collection of probe events. For more information about supported events, refer to <command>man stapprobes</command>. The <citetitle>SEE ALSO</citetitle> section of <command>man stapprobes</command> also contains links to other <command>man</command> pages that discuss supported events for specific subsystems and components.
 	</para>	
 </important>
+
+<remark>is reference appropriate? too advanced for readers (it seems so to me)? please advise.</remark> 
 	</section>
 	
 	<section id="systemtapscript-handlers">
@@ -142,6 +144,9 @@ probe begin
 <para>
 	The <command>printf ()</command> statement is one of the simplest handler tools for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
 </para>
+
+<remark>is "handler tool" appropriate?</remark>
+
 </formalpara>
 
 <programlisting>
@@ -175,6 +180,8 @@ probe syscall.open
 <xref linkend="syscall-open"/> instructs SystemTap to probe all entries to the system call <command>open</command>; for each event, it prints the current <command>execname()</command> (which is a string) and <command>pid()</command> (which is a number), followed by the word <command>open</command>. A snippet of this probe's output would look like:
 </para>
 
+<remark>editorial review: does a clarification that "variable1" is to "argument1", "variable2" is to "argument2", or is this clear enough?</remark>
+
 <screen>
 vmware-guestd(2206) open
 hald(2360) open
@@ -187,11 +194,13 @@ hald(2360) open
 </screen>
 
 <formalpara>
-	<title>Handler Functions</title>
+	<title>Handler Functions</title>	
 	<para>SystemTap supports a wide variety of handler functions that can be used as <command>printf ()</command> arguments. <xref linkend="syscall-open"/> uses the handler functions <command>execname()</command> (current process name) and <command>pid()</command> (current process ID).</para>
 </formalpara>		
-	<para>The following is a list of commonly-used handler functions:</para>
-	
+
+<remark>is "handler function" an appropriate term?</remark>
+
+	<para>The following is a list of commonly-used handler functions:</para>	
 <variablelist>
 
 <varlistentry>
@@ -254,6 +263,7 @@ hald(2360) open
 
 <para>For more information about supported handler functions, refer to <command>man stapfuncs</command>.</para>
 
+<remark>will need a complete listing of supported handler functions? also, handler function descriptions seem ambiguous, please advise.</remark>
 
 <!--	
 <para>
-- 
cgit 


From 4ef55e8308f34b73d6a0a69850900ae0d06499ce Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Thu, 11 Sep 2008 16:16:29 +1000
Subject: fixed tag error

---
 doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index d11eec2d..bed0bd06 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -145,9 +145,9 @@ probe begin
 	The <command>printf ()</command> statement is one of the simplest handler tools for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
 </para>
 
+</formalpara>
 <remark>is "handler tool" appropriate?</remark>
 
-</formalpara>
 
 <programlisting>
 printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]</replaceable>)
-- 
cgit 


From 6d24a6c909520290b1c508ae1624a218f19e93f1 Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Mon, 15 Sep 2008 15:21:57 +1000
Subject: minor revisions as per dsmith

---
 .../en-US/Introduction.xml                         |  4 +--
 doc/SystemTap_Beginners_Guide/en-US/Scripts.xml    | 39 ++++++++++++++++++----
 .../en-US/Understanding_How_SystemTap_Works.xml    |  2 +-
 3 files changed, 36 insertions(+), 9 deletions(-)

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
index 6f1b2a0a..b19f5e48 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml
@@ -5,7 +5,7 @@
 <chapter id="introduction">
 	<title>Introduction</title>
 	<para>
-		SystemTap is a tracing and probing tool that provides users deep technical insight into what the operating system (particularly, the kernel) is doing at any given time. It provides information similar to the output of tools like <command>netstat</command>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide information that is more "granular" in nature.  
+		SystemTap is a tracing and probing tool that provides users to study and monitor the activities of the operating system (particularly, the kernel) in fine detail. It provides information similar to the output of tools like <command>netstat</command>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide information that is more "granular" in nature.  
 	</para>
 	
 	<para>
@@ -23,7 +23,7 @@
 	
 	<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>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. 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 whose knowledge of the Linux kernel is little to none.</para>
 	
 	<para>In line with that, the main goals of the <citetitle>SystemTap Beginner's Guide</citetitle> are as follows:</para>
 	
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index bed0bd06..8426dc70 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -13,9 +13,12 @@
 		As stated in <xref linkend="understanding-how-systemtap-works"/>, SystemTap scripts are made up of two components: <emphasis>events</emphasis> and <emphasis>handlers</emphasis>. Once a SystemTap session is underway, SystemTap monitors the operating system for the specified events and executes the handlers as they occur. 
 	</para>
 	
+	
 <note>
 	<title>Note</title>
 	<para>An event and its corresponding handler is collectively called a <emphasis>probe</emphasis>. A SystemTap script can have multiple probes.</para>
+	
+	<para>A probe's handler is also commonly referred to as a <emphasis>probe body</emphasis>.</para>
 </note>	
 	
 	<para>
@@ -92,11 +95,34 @@ probe kernel.function("*@net/socket.c").return { }
 <varlistentry>
 	<term>syscall.<replaceable>[system_call]</replaceable></term>
 	<listitem>
-		<para>The entry to the system call <replaceable>[system_call]</replaceable>. Similar to <command>kerne.function</command>, appending a <command>return</command> to the statement specifies the exit of the system call. For example, to specify the entry of the system call <command>close</command>, use <command>syscall.close.return</command>.</para>
+		<para>The entry to the system call <replaceable>[system_call]</replaceable>. Similar to <command>kernel.function</command>, appending a <command>return</command> to the statement specifies the exit of the system call. For example, to specify the entry of the system call <command>close</command>, use <command>syscall.close.return</command>.</para>
 		
 		<para>To identify what system calls are made by a specific program/command, use <command>strace <replaceable>command</replaceable></command>.</para>
 	</listitem>	
 </varlistentry>
+
+<varlistentry>
+	<term>timer.ms()</term>
+	<listitem>
+		<para>An event that specifies a handler to be executed "after X number of milliseconds". For example:</para>
+		
+<example id="timer"><title>Using timer.ms</title>		
+<programlisting>
+probe timer.ms(4000)
+{
+	exit()
+}
+</programlisting>
+</example>
+
+<para>
+	<xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds (or 4 seconds). When used in conjunction with another probe that traps a large quantity of data, a probe using <command>timer.ms()</command> allows you to limit the information your script is collecting (and printing out).
+</para>	
+		
+	</listitem>	
+</varlistentry>
+
+<!--<remark>add timer.ms() to events list!</remark>-->
 <!--	
 <varlistentry>
 	<term></term>
@@ -119,7 +145,7 @@ probe kernel.function("*@net/socket.c").return { }
 	</section>
 	
 	<section id="systemtapscript-handlers">
-		<title>Handlers</title>
+		<title>Handlers/Probe Body</title>
 
 <para>
 Consider the following sample script:
@@ -169,10 +195,11 @@ printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]<
 	<title>Using Variables In printf ( ) Statements</title>
 <programlisting>
 # This probe will need to be manually terminated with Ctrl-C
-probe syscall.open
-{
-  printf ("%s(%d) open\n", execname(), pid())
-}
	
+probe syscall.open
+{
+  printf ("%s(%d) open\n", execname(), pid())
+}
+	
 </programlisting>	
 </example>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
index de5d41b0..76296507 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
@@ -34,7 +34,7 @@
 	<title>SystemTap Session</title>
 	<step><para>SystemTap first translates the script to C, running the system C compiler to create a kernel module from it.</para></step>
 	
-	<step><para>SystemTap then loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step>
+	<step><para>SystemTap loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step>
 		
 	<step><para>As the events occur, their corresponding handlers are executed.</para></step>
 	
-- 
cgit 


From 11b4229ae5bebfa15a3a742b31fe9c346a462650 Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Tue, 16 Sep 2008 13:35:57 +1000
Subject: minor edits as per david smith, flavio leitner

---
 doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 73 +++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index 8426dc70..bbd265c2 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -122,6 +122,29 @@ probe timer.ms(4000)
 	</listitem>	
 </varlistentry>
 
+<varlistentry>
+	<term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term>
+	<listitem>
+		<para>Allows you to probe functions within modules. For example:</para>
+		
+<example id="eventsmodules"><title>Module Probe</title>
+<programlisting>
+probe module("ext3").function("*") { }
+probe module("ext3").function("*").return { }
+</programlisting>	
+</example>
+
+	<para>
+		The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). 
+	</para>	
+	
+	<para>
+		A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. 
+	</para>	
+
+	</listitem>	
+</varlistentry>
+
 <!--<remark>add timer.ms() to events list!</remark>-->
 <!--	
 <varlistentry>
@@ -278,6 +301,56 @@ hald(2360) open
 		<para>If known, the name of the function in which the probe was placed.</para>
 	</listitem>	
 </varlistentry>
+
+<varlistentry>
+	<term>thread_indent()</term>
+	<listitem>
+		<para>This particular handler function is quite useful, providing you with a way to better organize your print results. When used with an indentation parameter (for example, <command>-1</command>), it allows the probe to internally store an "indentation counter" for each thread (identified by ID, as in <command>tid</command>). It then returns a string with some generic trace data along with an appropriate number of indentation spaces.</para>
+		
+		<para>The generic data included in the returned string includes a timestamp (number of microseconds since the most recent initial indentation), a process name, and the thread ID. This allows you to identify what functions were called, who called them, and the duration of each function call.
+		</para>	
+		
+		<para>
+			Consider the following example on the use of <command>thread_indent()</command>:
+		</para>
+		
+<example id="thread_indent"><title>Using thread_indent()</title>
+<programlisting>
+probe kernel.function("*@net/socket.c") 
+{
+	printf ("%s -> %s\n", thread_indent(1), probefunc())
+}
+probe kernel.function("*@net/socket.c").return 
+{
+	printf ("%s &lt;- %s\n", thread_indent(-1), probefunc())
+}
+</programlisting>
+</example>
+	<para><xref linkend="thread_indent"/> prints out the <command>thread_indent()</command> and probe functions at each event in the following format:</para>
+	
+<screen>
+     0 ftp(7223): -&gt; sys_socketcall
+  1159 ftp(7223): -&gt; sys_socket
+  2173 ftp(7223):   -&gt; __sock_create
+  2286 ftp(7223):    -&gt; sock_alloc_inode
+  2737 ftp(7223):    &lt;- sock_alloc_inode
+  3349 ftp(7223):    -&gt; sock_alloc
+  3389 ftp(7223):    &lt;- sock_alloc
+  3417 ftp(7223):   &lt;- __sock_create
+  4117 ftp(7223):   -&gt; sock_create
+  4160 ftp(7223):   &lt;- sock_create
+  4301 ftp(7223):   -&gt; sock_map_fd
+  4644 ftp(7223):    -&gt; sock_map_file
+  4699 ftp(7223):    &lt;- sock_map_file
+  4715 ftp(7223):   &lt;- sock_map_fd
+  4732 ftp(7223): &lt;- sys_socket
+  4775 ftp(7223): &lt;- sys_socketcall
+</screen>
+
+<remark>remember to add a reference later to "tapsets" from here, to clarify that thread_indent is defined in tapsets as a special function of sorts</remark>
+	
+	</listitem>	
+</varlistentry>
 <!--	
 <varlistentry>
 	<term></term>
-- 
cgit