From 6820dda776595280e6dc535df32648b47d21e329 Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Tue, 5 May 2009 15:43:56 +1000
Subject: added ioblktime.stp to guide

---
 .../en-US/Useful_Scripts-ioblktime.xml             | 111 +++++++++++++++++++++
 .../en-US/Useful_SystemTap_Scripts.xml             |   2 +
 2 files changed, 113 insertions(+)
 create mode 100644 doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-ioblktime.xml

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-ioblktime.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-ioblktime.xml
new file mode 100644
index 00000000..e586d81a
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-ioblktime.xml
@@ -0,0 +1,111 @@
+<?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="ioblktimesect">
+		<title>Periodically Print I/O Block Time</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring I/O block time</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring I/O block time</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring I/O block time</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<indexterm>
+<primary>I/O block time, monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<indexterm>
+<primary>printing I/O block time (periodically)</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+	<para>
+		This section describes how to track the amount of time each block I/O requests spends 
+		waiting for completion. This is useful in determining whether there are too many
+		outstanding block I/O operations at any given time.
+	</para>
+	
+<formalpara id="ioblktime">
+	<title>ioblktime.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/io/ioblktime.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+<!-- <remark>what does $count do, specifically?</remark> -->
+
+<para>
+	<xref linkend="ioblktime"/> computes the average waiting time for block I/O per device, 
+	and prints a list every 10 seconds. As always, you can revise this refresh rate by 
+	editing the specified value in <command>probe timer.s(10), end {</command>.
+</para>	
+<para>	
+	In some cases, there can be too many outstanding block 
+	I/O operations, at which point the script can exceed the default number of 
+	<command>MAXMAPENTRIES</command>. <command>MAXMAPENTRIES</command> is the maximum number of 
+	rows in an array if the array size is not specified explicitly when declared. If the script
+	exceeds the default <command>MAXMAPENTRIES</command> value of 2048, run the script again with 
+	the <command>stap</command> option <command>-DMAXMAPENTRIES=10000</command>.
+</para>
+	
+
+<example id="ioblktimeoutput">
+	<title><xref linkend="ioblktime"/> Sample Output</title>
+<screen>
+    device  rw total (us)      count   avg (us)
+       sda   W       9659          6       1609
+      dm-0   W      20278          6       3379
+      dm-0   R      20524          5       4104
+       sda   R      19277          5       3855
+</screen>
+</example>
+
+<para>
+	<xref linkend="ioblktimeoutput"/> displays the device name, operations performed 
+	(<command>rw</command>), total wait time of all operations (<command>total(us)</command>), 
+	number of operations (<command>count</command>), and average
+	wait time for all those operations (<command>avg (us)</command>). The times tallied by the 
+	script are in microseconds.
+</para>	
+	
+<!--
+global reads, writes, total_io
+
+probe kernel.function("vfs_read") {
+reads[execname()] += $count
+}
+
+probe kernel.function("vfs_write") {
+writes[execname()] += $count
+}
+
+# print top 10 IO processes every 5 seconds
+probe timer.s(5) {
+foreach (name in writes)
+total_io[name] += writes[name]
+foreach (name in reads)
+total_io[name] += reads[name]
+printf ("%16s\t%10s\t%10s\n", "Process", "KB Read", "KB Written")
+foreach (name in total_io- limit 10)
+printf("%16s\t%10d\t%10d\n", name,
+reads[name]/1024, writes[name]/1024)
+delete reads
+delete writes
+delete total_io
+print("\n")
+}
+-->
+
+</section>
\ No newline at end of file
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 80e68770..4d999b53 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -56,6 +56,7 @@
 <!-- 	<xi:include href="Useful_Scripts-Kernel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
 	<xi:include href="Useful_Scripts-inodewatch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-inodewatch2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include condition="fedora" href="Useful_Scripts-ioblktime.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 </section>
 
 <section id="mainsect-profiling">
@@ -71,6 +72,7 @@
 <!-- 	removed; handler function no longer working as expected
 	<xi:include href="Useful_Scripts-kernelprofiling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
 
+	
 <xi:include href="Useful_Scripts-futexes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
 <!--	<xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-- 
cgit