added Useful_Scripts-nettop.xml

3 files changed, 139 insertions, 7 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
index 0c191cff..69877c5b 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
@@ -95,19 +95,19 @@ probe end{
 <para><xref linkend="scriptdisktop"/> outputs the top ten processes responsible for the heaviest reads/writes to disk. <xref linkend="disktopoutput"/> displays a sample output for this script, and includes the following data per listed process:</para>
 
 <itemizedlist>
-	<listitem><para><command>UID</command> &mdash; user ID. A user ID of <command>0</command> refers to the root user.</para></listitem>
+	<listitem><para><computeroutput>UID</computeroutput> &mdash; user ID. A user ID of <computeroutput>0</computeroutput> refers to the root user.</para></listitem>
 	
-	<listitem><para><command>PID</command> &mdash; the ID of the listed process.</para></listitem>
+	<listitem><para><computeroutput>PID</computeroutput> &mdash; the ID of the listed process.</para></listitem>
 	
-	<listitem><para><command>PPID</command> &mdash; the process ID of the listed process's <emphasis>parent process</emphasis>.</para></listitem>
+	<listitem><para><computeroutput>PPID</computeroutput> &mdash; the process ID of the listed process's <emphasis>parent process</emphasis>.</para></listitem>
 	
-	<listitem><para><command>CMD</command> &mdash; the name of the listed process.</para></listitem>
+	<listitem><para><computeroutput>CMD</computeroutput> &mdash; the name of the listed process.</para></listitem>
 	
-	<listitem><para><command>DEVICE</command> &mdash; which storage device the listed process is reading from or writing to.</para></listitem>
+	<listitem><para><computeroutput>DEVICE</computeroutput> &mdash; which storage device the listed process is reading from or writing to.</para></listitem>
 	
-	<listitem><para><command>T</command> &mdash; the type of action performed by the listed process; <command>W</command> refers to write, while <command>R</command> refers to read.</para></listitem>
+	<listitem><para><computeroutput>T</computeroutput> &mdash; the type of action performed by the listed process; <computeroutput>W</computeroutput> refers to write, while <computeroutput>R</computeroutput> refers to read.</para></listitem>
 	
-	<listitem><para><command>BYTES</command> &mdash; the amount of data read to or written from disk.</para></listitem>
+	<listitem><para><computeroutput>BYTES</computeroutput> &mdash; the amount of data read to or written from disk.</para></listitem>
 </itemizedlist>	
 	
 	
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
new file mode 100644
index 00000000..d56cbfc1
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml
@@ -0,0 +1,131 @@
+<?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="nettopsect">
+		<title>Kernel Profiling</title>
+		
+		
+<remark>
+	WAR STORY: Top network users by PID http://sourceware.org/systemtap/wiki/WSNetTop?highlight=((WarStories))
+</remark>
+		
+<remark>
+	probably http://sourceware.org/systemtap/examples/network/nettop.stp
+</remark>	
+				
+
+<para>This section describes how to profile network activity. <xref linkend="nettop"/> provides a glimpse into how much network traffic each process is generating on a machine.</para> 
+
+<formalpara id="nettop">
+		<title>nettop.stp</title>
+<para>
+<programlisting>
+global ifxmit, ifrecv, ifdevs, ifpid, execname, user
+
+probe netdev.transmit
+{
+        p = pid()
+        execname[p] = execname()
+        user[p] = uid()
+        ifdevs[p, dev_name] = dev_name
+	ifxmit[p, dev_name] &lt;&lt;&lt; length
+        ifpid[p, dev_name] ++
+}
+
+probe netdev.receive
+{
+        p = pid()
+        execname[p] = execname()
+        user[p] = uid()
+        ifdevs[p, dev_name] = dev_name
+	ifrecv[p, dev_name] &lt;&lt;&lt; length
+        ifpid[p, dev_name] ++
+}
+
+
+function print_activity()
+{
+        printf("%5s %5s %-7s %7s %7s %7s %7s %-15s\n",
+                "PID", "UID", "DEV", "XMIT_PK", "RECV_PK",
+                "XMIT_KB", "RECV_KB", "COMMAND")
+
+        foreach ([pid, dev] in ifpid-) {
+                n_xmit = @count(ifxmit[pid, dev])
+                n_recv = @count(ifrecv[pid, dev])
+                printf("%5d %5d %-7s %7d %7d %7d %7d %-15s\n",
+                        pid, user[pid], dev, n_xmit, n_recv,
+                        n_xmit ? @sum(ifxmit[pid, dev])/1024 : 0,
+                        n_recv ? @sum(ifrecv[pid, dev])/1024 : 0,
+                        execname[pid])
+        }
+
+        print("\n")
+
+        delete execname
+        delete user
+        delete ifdevs
+        delete ifxmit
+        delete ifrecv
+        delete ifpid
+}
+
+probe timer.ms(5000)
+{
+        print_activity()
+}
+</programlisting>
+</para>
+</formalpara>		
+
+<para><xref linkend="nettop"/> tracks which processes are generating network traffic on the system, and provides the following information about each process:</para>
+
+<itemizedlist>
+	<listitem><para><computeroutput>PID</computeroutput> &mdash; the ID of the listed process.</para></listitem>
+	
+	<listitem><para><computeroutput>UID</computeroutput> &mdash; user ID. A user ID of <computeroutput>0</computeroutput> refers to the root user.</para></listitem>
+
+	<listitem><para><computeroutput>DEV</computeroutput> &mdash; which ethernet device the process used to send / receive data (e.g. eth0, eth1)</para></listitem>
+	<listitem><para><computeroutput>XMIT_PK</computeroutput> &mdash; number of packets transmitted by the process</para></listitem>
+	<listitem><para><computeroutput>RECV_PK</computeroutput> &mdash; number of packets received by the process</para></listitem>
+	<listitem><para><computeroutput>XMIT_KB</computeroutput> &mdash; amount of data sent by the process, in kilobytes</para></listitem>
+	<listitem><para><computeroutput>RECV_KB</computeroutput> &mdash; amount of data received by the service, in kilobytes</para></listitem>
+</itemizedlist>	
+
+<para><xref linkend="nettop"/> provides network profile sampling every 5 seconds. You can change this setting by editing <command>probe timer.ms(5000)</command> accordingly. <xref linkend="nettopoutput"/> contains an excerpt of the output from <xref linkend="nettop"/> over a 20-second period:</para>
+
+
+<example id="nettopoutput">
+	<title><xref linkend="nettop"/> Sample Output</title>
+<screen>
+[...]
+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

+    0     0 eth0          0       5       0       0 swapper        

+11178     0 eth0          2       0       0       0 synergyc       

+

+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

+ 2886     4 eth0         79       0       5       0 cups-polld     

+11362     0 eth0          0      61       0       5 firefox        

+    0     0 eth0          3      32       0       3 swapper        

+ 2886     4 lo            4       4       0       0 cups-polld     

+11178     0 eth0          3       0       0       0 synergyc       

+

+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

+    0     0 eth0          0       6       0       0 swapper        

+ 2886     4 lo            2       2       0       0 cups-polld     

+11178     0 eth0          3       0       0       0 synergyc       

+ 3611     0 eth0          0       1       0       0 Xorg           

+

+  PID   UID DEV     XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND        

+    0     0 eth0          3      42       0       2 swapper        

+11178     0 eth0         43       1       3       0 synergyc       

+11362     0 eth0          0       7       0       0 firefox        

+ 3897     0 eth0          0       1       0       0 multiload-apple

+[...]
+</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 03cb6b40..ecfc2341 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -31,6 +31,7 @@
 	<xi:include href="Useful_Scripts-functioncalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<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-nettop.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" />
 	<xi:include href="Useful_Scripts-Syscalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />