--- /dev/null
+<?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)\r
+ sda W 9659 6 1609\r
+ dm-0 W 20278 6 3379\r
+ dm-0 R 20524 5 4104\r
+ sda R 19277 5 3855\r
+</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