<?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="../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 vfs.read.return {
  if ($return > 0) {
    reads[pid(),execname()] += $return
    total_io[pid(),execname()] += $return
  }
}

probe vfs.write.return {
  if ($return > 0) {
    writes[pid(),execname()] += $return
    total_io[pid(),execname()] += $return
  }
}

function humanreadable(bytes) {
  if (bytes > 1024*1024*1024) {
    return sprintf("%d GiB", bytes/1024/1024/1024)
  } else if (bytes > 1024*1024) {
    return sprintf("%d MiB", bytes/1024/1024)
  } else if (bytes > 1024) {
    return sprintf("%d KiB", bytes/1024)
  } else {
    return sprintf("%d   B", bytes)
  }
}

probe timer.s(1) {
  foreach([p,e] in total_io- limit 10)
    printf("%8d %15s r: %12s w: %12s\n",
           p, e, humanreadable(reads[p,e]),
           humanreadable(writes[p,e]))
  printf("\n")
  # Note we don't zero out reads, writes and total_io,
  # so the values are cumulative since the script started.
}
-->

</section>


