added section for traceio.stp (tracking cumulative IO)

4 files changed, 87 insertions, 1 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Section.xml b/doc/SystemTap_Beginners_Guide/en-US/Section.xml
new file mode 100644
index 00000000..c5895624
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Section.xml
@@ -0,0 +1,12 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+	<section id="SystemTap_Beginners_Guide-Test-Section_1_Test">
+		<title>Section 1 Test</title>
+		<para>
+			Test of a section
+		</para>
+	</section>
+
+
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml
index fe249428..42b9e025 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml
@@ -72,5 +72,5 @@ probe timer.s(5) {
 </screen>
 </example>
 
-<para><xref linkend="iotopoutput"/> displays top I/O writes and reads within a random 10-second interval. Note that <xref linkend="iotop"/> is recursive, as it also detects I/O resulting from SystemTap activity &mdash; <xref linkend="iotopoutput"/> also displays reads done by <command>staprun</command>.</para>
+<para><xref linkend="iotopoutput"/> displays top I/O writes and reads within a random 10-second interval. Note that <xref linkend="iotop"/> also detects I/O resulting from SystemTap activity &mdash; <xref linkend="iotopoutput"/> also displays reads done by <command>staprun</command>.</para>
 </section>
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml
new file mode 100644
index 00000000..51f57f6f
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml
@@ -0,0 +1,73 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+	<section id="traceiosect">
+		<title>Track Cumulative IO</title>
+		<para>
+			This section describes how to track the cumulative amount of I/O to the system.
+		</para>
+		
+<formalpara id="traceio">
+	<title>traceio.stp</title>
+<para>
+<programlisting>
+global reads, writes, total_io
+
+probe kernel.function("vfs_read").return {
+	reads[execname()] += $return
+}
+
+probe kernel.function("vfs_write").return {
+	writes[execname()] += $return
+}
+
+probe timer.s(1) {
+	foreach (p in reads)
+		total_io[p] += reads[p]
+	foreach (p in writes)
+		total_io[p] += writes[p]
+	foreach(p in total_io- limit 10)
+		printf("%15s r: %8d KiB w: %8d KiB\n",
+			p, reads[p]/1024,
+			writes[p]/1024)
+		printf("\n")
+	# Note we don't zero out reads, writes and total_io,
+	# so the values are cumulative since the script started.
+}
+</programlisting>
+</para>
+</formalpara>
+
+<para><xref linkend="traceio"/> is similar to <xref linkend="iotop"/> (from <xref linkend="iotopsect"/>); both SystemTap scripts print out the top ten executables generating I/O traffic over time. However, <xref linkend="traceio"/> tracks the <emphasis>cumulative</emphasis> amount of I/O reads and writes done by the system's top ten executables. This information is tracked and printed out in 1-second intervals and in descending order.</para>
+
+<example id="traceiooutput">
+	<title><xref linkend="traceio"/> Sample Output</title>
+<screen>
+[...]
+           Xorg r:   583401 KiB w:        0 KiB
+       floaters r:       96 KiB w:     7130 KiB
+multiload-apple r:      538 KiB w:      537 KiB
+           sshd r:       71 KiB w:       72 KiB
+pam_timestamp_c r:      138 KiB w:        0 KiB
+        staprun r:       51 KiB w:       51 KiB
+          snmpd r:       46 KiB w:        0 KiB
+          pcscd r:       28 KiB w:        0 KiB
+     irqbalance r:       27 KiB w:        4 KiB
+          cupsd r:        4 KiB w:       18 KiB
+
+           Xorg r:   588140 KiB w:        0 KiB
+       floaters r:       97 KiB w:     7143 KiB
+multiload-apple r:      543 KiB w:      542 KiB
+           sshd r:       72 KiB w:       72 KiB
+pam_timestamp_c r:      138 KiB w:        0 KiB
+        staprun r:       51 KiB w:       51 KiB
+          snmpd r:       46 KiB w:        0 KiB
+          pcscd r:       28 KiB w:        0 KiB
+     irqbalance r:       27 KiB w:        4 KiB
+          cupsd r:        4 KiB w:       18 KiB
+</screen>
+</example>		
+	</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 03e515ff..d8ec61f2 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -22,6 +22,7 @@
 	<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-iotop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-traceio.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" />
 	<xi:include href="Useful_Scripts-Signals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />