summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ChangeLog8
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml10
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Installation.xml16
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml137
-rw-r--r--doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml1
-rw-r--r--doc/SystemTap_Tapset_Reference/tapsets.tmpl1
-rw-r--r--doc/Tapset_Reference_Guide/en-US/Author_Group.xml2
-rwxr-xr-x[-rw-r--r--]doc/Tapset_Reference_Guide/publicanize.sh10
8 files changed, 181 insertions, 4 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index f2def218..cf9e2823 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,13 @@
2009-02-05 William Cohen <wcohen@redhat.com>
+ * T_R_G/publicanize.sh: Make executable.
+
+2009-02-05 William Cohen <wcohen@redhat.com>
+
+ * S_T_R/tapsets.tmpl: Add contrib tag to quiet warnings.
+
+2009-02-05 William Cohen <wcohen@redhat.com>
+
* S_T_R/tapsets.tmpl: Minor correction for signal.stp chapter.
2009-02-02 Stan Cox <scox@redhat.com>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml b/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
index 4d81c745..0c55a7ee 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Author_Group.xml
@@ -13,4 +13,14 @@
</affiliation>
<email>ddomingo@redhat.com</email>
</author>
+
+ <author>
+ <firstname>William</firstname>
+ <surname>Cohen</surname>
+ <affiliation>
+ <orgname>Engineering Services and Operations</orgname>
+ <orgdiv>Performance Tools</orgdiv>
+ </affiliation>
+ <email>wcohen@redhat.com</email>
+ </author>
</authorgroup>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index 1ff2ff29..3a45d269 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -186,8 +186,22 @@ uname -r
<note>
<title>Note</title>
<para>Running <xref linkend="stapprep"/> as root will display the required kernel packages <emphasis>and</emphasis> install them as well, provided that <command>yum</command> and <command>yum-utils</command> are configured properly.</para>
-</note>
+<para condition="RedHat">
+ In order for <command>yum</command> to find and download the required kernel packages, you need to
+ point it to a repository containing those packages. Most required kernel packages can be found at
+ <ulink url="ftp://ftp.redhat.com/pub/redhat/linux/enterprise/"/>; navigate there until you find the
+ appropriate <filename>Debuginfo</filename> directory for your system. Configure
+ <command>yum</command> accordingly by adding a new "debug" <command>yum</command> repository file under <filename>/etc/yum.repos.d</filename> containing the following lines:
+</para>
+
+<programlisting condition="RedHat">
+[rhel-debuginfo]
+name=Red Hat Enterprise Linux $releasever - $basearch - Debug
+baseurl=ftp://ftp.redhat.com/pub/redhat/linux/enterprise/$releasever/en/os/$basearch/Debuginfo/
+enabled=1
+</programlisting>
+</note>
<!-- Running <xref linkend="stapprep"/> without any arguments will display and install the required kernel information packages for the currently loaded kernel. If you wish to probe a kernel other than the one currently loaded, you can pass a specific kernel version as an argument to <xref linkend="stapprep"/>; the script will then install that kernel's corresponding kernel information packages.
</para> -->
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
new file mode 100644
index 00000000..32ce8319
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-timeout.xml
@@ -0,0 +1,137 @@
+<?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="timeoutssect">
+<title>Monitoring Polling Applications</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring polling applications</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring polling applications</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring polling applications</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<!--
+<indexterm>
+<primary>counting function calls</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+-->
+
+<indexterm>
+<primary>polling applications, monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<remark>
+uses systemtap/testsuite/systemtap.examples/profiling/timeout.stp
+</remark>
+
+
+ <para>
+ This section how to identify and monitor which applications are polling. Doing so allows you to track
+ unnecessary or excessive polling, which can help you pinpoint areas for improvement in terms of CPU usage
+ and power savings.
+ </para>
+
+<formalpara id="timeouts">
+ <title>timeout.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/testsuite/systemtap.examples/profiling/timeout.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+ <para>
+ <xref linkend="timeouts"/> tracks how many times each application used the following system calls over time:
+ </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>
+ 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.
+ </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>
+
+<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>
+<screen>
+ uid | poll select epoll itimer futex nanosle signal| process
+28937 | 148793 0 0 4727 37288 0 0| firefox
+22945 | 0 56949 0 1 0 0 0| scim-bridge
+ 0 | 0 0 0 36414 0 0 0| swapper
+ 4275 | 23140 0 0 1 0 0 0| mixer_applet2
+ 4191 | 0 14405 0 0 0 0 0| scim-launcher
+22941 | 7908 1 0 62 0 0 0| gnome-terminal
+ 4261 | 0 0 0 2 0 7622 0| escd
+ 3695 | 0 0 0 0 0 7622 0| gdm-binary
+ 3483 | 0 7206 0 0 0 0 0| dhcdbd
+ 4189 | 6916 0 0 2 0 0 0| scim-panel-gtk
+ 1863 | 5767 0 0 0 0 0 0| iscsid
+ 2562 | 0 2881 0 1 0 1438 0| pcscd
+ 4257 | 4255 0 0 1 0 0 0| gnome-power-man
+ 4278 | 3876 0 0 60 0 0 0| multiload-apple
+ 4083 | 0 1331 0 1728 0 0 0| Xorg
+ 3921 | 1603 0 0 0 0 0 0| gam_server
+ 4248 | 1591 0 0 0 0 0 0| nm-applet
+ 3165 | 0 1441 0 0 0 0 0| xterm
+29548 | 0 1440 0 0 0 0 0| httpd
+ 1862 | 0 0 0 0 0 1438 0| iscsid
+</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 8b7fc741..ed089361 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -62,6 +62,7 @@
<xi:include href="Useful_Scripts-functioncalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<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" />
</section>
<!-- removed; handler function no longer working as expected
<xi:include href="Useful_Scripts-kernelprofiling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
index 4310f39a..d6b3b309 100644
--- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl
+++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
@@ -10,6 +10,7 @@
<author>
<firstname>William</firstname>
<surname>Cohen</surname>
+ <contrib></contrib>
<affiliation>
<address>
<email>wcohen@redhat.com</email>
diff --git a/doc/Tapset_Reference_Guide/en-US/Author_Group.xml b/doc/Tapset_Reference_Guide/en-US/Author_Group.xml
index d795efba..67ea97dc 100644
--- a/doc/Tapset_Reference_Guide/en-US/Author_Group.xml
+++ b/doc/Tapset_Reference_Guide/en-US/Author_Group.xml
@@ -14,7 +14,7 @@
<email>ddomingo@redhat.com</email>
</author>
<author>
- <firstname>Will</firstname>
+ <firstname>William</firstname>
<surname>Cohen</surname>
<affiliation>
<orgname>Engineering Services and Operations</orgname>
diff --git a/doc/Tapset_Reference_Guide/publicanize.sh b/doc/Tapset_Reference_Guide/publicanize.sh
index ca78d713..96c20a11 100644..100755
--- a/doc/Tapset_Reference_Guide/publicanize.sh
+++ b/doc/Tapset_Reference_Guide/publicanize.sh
@@ -6,11 +6,15 @@ cp ../SystemTap_Tapset_Reference/tapsets.xml en-US/Tapset_Reference_Guide.xml ;
#remove all excess whitespace
sed -i -e 's/^\s*//g' en-US/Tapset_Reference_Guide.xml ;
+#re-convert programlisting tags
+sed -i -e 's/&lt;programlisting&gt;/<programlisting>/g' en-US/Tapset_Reference_Guide.xml;
+sed -i -e 's/&lt;\/programlisting&gt;/<\/programlisting>/g' en-US/Tapset_Reference_Guide.xml;
+
#replace header
cat en-US/Tapset_Reference_Guide.xml |
perl -p -e 'undef $/;s|<bookinfo>\n<title>SystemTap Tapset Reference Manual</title>|<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|msg' |
-perl -p -e 'undef $/;s|<authorgroup>\n<author>\n<firstname>William</firstname>\n<surname>Cohen</surname>\n<affiliation>\n<address>\n<email>wcohen\@redhat.com</email>\n</address>\n</affiliation>\n</author>\n</authorgroup>||msg' |
+perl -p -e 'undef $/;s|<authorgroup>\n<author>\n<firstname>William</firstname>\n<surname>Cohen</surname>\n<contrib></contrib>\n<affiliation>\n<address>\n<email>wcohen\@redhat.com</email>\n</address>\n</affiliation>\n</author>\n</authorgroup>||msg' |
perl -p -e 'undef $/;s|<copyright>\n<year>2008, 2009</year>\n<holder>Red Hat, Inc.</holder>\n</copyright>||msg' |
perl -p -e 'undef $/;s|<legalnotice>\n<para>\nThis documentation is free software\; you can redistribute\nit and/or modify it under the terms of the GNU General Public\nLicense version 2 as published by the Free Software Foundation.\n</para>||msg' |
perl -p -e 'undef $/;s|<para>\nThis program is distributed in the hope that it will be\nuseful, but WITHOUT ANY WARRANTY; without even the implied\nwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\nSee the GNU General Public License for more details.\n</para>||msg' |
@@ -20,7 +24,9 @@ perl -p -e 'undef $/;s|<toc></toc>||msg' |
perl -p -e 'undef $/;s|\n\n\n\n\n\n\n\n\n\n\n\n\n\n||msg' |
perl -p -e 'undef $/;s|<programlisting>\n|<programlisting>\n<emphasis>(sfunction) <\/emphasis>|msg' |
perl -p -e 'undef $/;s|<para>\n</para>||msg' |
-perl -p -e 'undef $/;s|<para>\n\n</para>||msg' > clean.xml
+perl -p -e 'undef $/;s|<para>\n\n</para>||msg' |
+perl -p -e 'undef $/;s|<para>\n<programlisting>|<programlisting>|msg' |
+perl -p -e 'undef $/;s|</programlisting>\n</para>|</programlisting>|msg' > clean.xml
cp clean.xml en-US/Tapset_Reference_Guide.xml
rm clean.xml
generated by cgit (git 2.34.1) at 2025-08-05 09:42:15 +0000