added topsys.stp to examples (profiling)

3 files changed, 143 insertions, 12 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
index 32ce8319..719f5c6d 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
@@ -67,10 +67,11 @@ uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
 	</itemizedlist>	
 
 	<para>
-		In some applications, these system calls are used excessively. For example, an application that 
-		needs to perform a task once every hour could be configured (or even designed) to check the 
-		clock every second if the hour has already passed. Such design idioms are throwbacks to earlier 
-		kernel versions, which used a periodic tick.
+		In some applications, these system calls are used excessively. As such, they are normally identified as "likely
+		culprits" for polling applications. Note, however, that an application may be using a different system
+		call to poll excessively; sometimes, it is useful to find out the top system calls used by the system (refer to 
+		<xref linkend="topsyssect"/> for instructions). Doing so can help you identify any additional suspects, which you 
+		can add to <xref linkend="timeouts"/> for tracking.
 	</para>
 		
 	
@@ -88,13 +89,6 @@ uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
 <primary>timer.s(), sample usage</primary>
 <secondary>examples of SystemTap scripts</secondary>
 </indexterm>
-
-<para>
-	You can increase the sample time by editing the timer in the second probe (<command>timer.s()</command>). 
-	The output of <xref linkend="countcalls"/> contains the name and UID of the top 20 polling applications, 
-	along with how many times each application performed each polling system call (over time). 
-	<xref linkend="timeoutsoutput"/> contains an excerpt of the script:
-</para>
 	
 <example id="timeoutsoutput">
 	<title><xref linkend="timeouts"/> Sample Output</title>
@@ -132,6 +126,11 @@ foreach (fn+ in called)  # Sort by function name
 printf("%s %d\n", fn, @count(called[fn]))
 exit()
 }-->
-
+<para>
+	You can increase the sample time by editing the timer in the second probe (<command>timer.s()</command>). 
+	The output of <xref linkend="countcalls"/> contains the name and UID of the top 20 polling applications, 
+	along with how many times each application performed each polling system call (over time). 
+	<xref linkend="timeoutsoutput"/> contains an excerpt of the script:
+</para>
 	</section>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.xml
new file mode 100644
index 00000000..700ef4ed
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-topsys.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="topsyssect">
+<title>Tracking Most Frequently Used System Calls</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring system calls</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring system calls</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring system calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>		
+		
+<!--
+<indexterm>
+<primary>counting function calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+-->
+
+<indexterm>
+<primary>system calls, monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+		
+<remark>
+uses systemtap/testsuite/systemtap.examples/profiling/topsys.stp
+</remark>	
+				
+		
+	<para>
+		<xref linkend="timeouts"/> from <xref linkend="timeoutssect"/> helps you identify which applications
+		are polling by pointing out which ones used the following system calls most frequently:
+	</para>
+	
+	<itemizedlist>
+		<listitem><para><command>poll</command></para></listitem>
+		<listitem><para><command>select</command></para></listitem>
+		<listitem><para><command>epoll</command></para></listitem>
+		<listitem><para><command>itimer</command></para></listitem>
+		<listitem><para><command>futex</command></para></listitem>
+		<listitem><para><command>nanosleep</command></para></listitem>
+		<listitem><para><command>signal</command></para></listitem>
+	</itemizedlist>		
+		
+	<para>
+		However, in some systems, a different system call might be responsible for excessive polling. If you suspect 
+		that a polling application might is using a different system call to poll, you need to identify first the top
+		system calls used by the system. To do this, use <xref linkend="topsys"/>.
+	</para>	
+
+<formalpara id="topsys">
+	<title>topsys.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/profiling/topsys.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>		
+	
+<para>
+	<xref linkend="topsys"/> lists the top 20 system calls used by the system per 5-second interval. It also lists 
+	how many times each system call was used during that period. Refer to <xref linkend="topsysoutput"/> for a sample output. 
+</para>	
+	
+<indexterm>
+<primary>script examples</primary>
+<secondary>timer.s(), sample usage</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>timer.s(), sample usage</secondary>
+</indexterm>
+
+<indexterm>
+<primary>timer.s(), sample usage</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+
+<example id="topsysoutput">
+	<title><xref linkend="topsys"/> Sample Output</title>
+<screen>
+--------------------------------------------------------------

+                  SYSCALL      COUNT

+             gettimeofday       1857

+                     read       1821

+                    ioctl       1568

+                     poll       1033

+                    close        638

+                     open        503

+                   select        455

+                    write        391

+                   writev        335

+                    futex        303

+                  recvmsg        251

+                   socket        137

+            clock_gettime        124

+           rt_sigprocmask        121

+                   sendto        120

+                setitimer        106

+                     stat         90

+                     time         81

+                sigreturn         72

+                    fstat         66

+--------------------------------------------------------------

+</screen>
+</example>
+<!--probe kernel.function(@1) {  # probe function passed as argument from stdin
+called[probefunc()] &lt;&lt;&lt; 1  # add a count efficiently
+}
+global called          
+probe end,timer.ms(30000) {
+foreach (fn+ in called)  # Sort by function name
+#       (fn in called-)  # Sort by call count (in decreasing order)
+printf("%s %d\n", fn, @count(called[fn]))
+exit()
+}-->
+
+	</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 ed089361..c2c83a82 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -63,6 +63,7 @@
 	<xi:include href="Useful_Scripts-paracallgraph.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-threadtimes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-timeout.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-topsys.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 </section>
 <!-- 	removed; handler function no longer working as expected
 	<xi:include href="Useful_Scripts-kernelprofiling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->