<?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>
<indexterm>
<primary>script examples</primary>
<secondary>tracking cumulative I/O</secondary>
</indexterm>

<indexterm>
<primary>examples of SystemTap scripts</primary>
<secondary>tracking cumulative I/O</secondary>
</indexterm>

<indexterm>
<primary>tracking cumulative I/O</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>		
		
<indexterm>
<primary>cumulative I/O, tracking</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>
		
<indexterm>
<primary>monitoring cumulative I/O</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

<indexterm>
<primary>printing I/O activity (cumulative)</primary>
<secondary>examples of SystemTap scripts</secondary>
</indexterm>

		<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>
<xi:include parse="text" href="extras/testsuite/systemtap.examples/io/traceio.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</para>
</formalpara>
<!--
<remark>what do $return, $length, and $count return, specifically? when i substituted $return for $length here, script still ran but gave me bigger numbers. errored out with $length. where documented?</remark>-->

<para>
	<xref linkend="traceio"/> prints the top ten executables generating I/O traffic over time. In
	addition, it also tracks the cumulative amount of I/O reads and writes done by those ten 
	executables. This information is tracked and printed out in 1-second intervals, and in 
	descending order.
</para>
<!-- next 3 indexterms for $return -->
<indexterm>
	<primary>local variables</primary>
	<secondary>sample usage</secondary>
	<tertiary>$return</tertiary>
</indexterm>

<indexterm>
	<primary>variables (local)</primary>
	<secondary>sample usage</secondary>
	<tertiary>$return</tertiary>
</indexterm>

<indexterm>
	<primary>$return</primary>
	<secondary>sample usage</secondary>
	<tertiary>local variables</tertiary>
</indexterm>
<para>
	Note that <xref linkend="traceio"/> also uses the local variable <command>$return</command>,
	which is also used by <xref linkend="scriptdisktop"/> from <xref linkend="disktop"/>.
</para>

<!--<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>		
<!--	
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.
}-->

</section>


