diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide')
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml | 147 | ||||
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 130 | ||||
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml | 3 | ||||
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml | 36 | ||||
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml | 212 | ||||
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml | 147 | ||||
| -rwxr-xr-x | doc/SystemTap_Beginners_Guide/en-US/images/gnuplotsample.png | bin | 0 -> 8286 bytes |
7 files changed, 621 insertions, 54 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml new file mode 100644 index 00000000..cf57f5b2 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml @@ -0,0 +1,147 @@ +<?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="cross-compiling"> + <title>Cross-Instrumentation</title> + +<remark>cross-compiling script from here: http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html</remark> + +<remark>above; add short description, significance, howto, script (test first)</remark> + <para> + When users run a SystemTap script, SystemTap builds a kernel module out of that script. SystemTap then loads the module onto the kernel, allowing it to extract the specified data directly from the kernel (refer to <xref linkend="systemtapsession"/> in <xref linkend="understanding-architecture-tools"/> for more information). + </para> + + <para> + Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in <xref linkend="installproper"/>). This could mean that if you want to run SystemTap on ten systems, you'd need to deploy SystemTap on <emphasis>all</emphasis> those systems. + </para> + + <para> + In some cases, this may be neither feasible nor desired. For instance, running SystemTap on 25 systems — all of which are using a different kernel — may require fully deploying SystemTap on all 25 machines. This task may even increase in complexity if some (or all) systems are remote from the administrator. Sometimes, corporate policy may prohibit an administrator from installing a debug version of an RPM on specific machines, which will prevent the deployment of SystemTap altogether. + </para> + + <para> + To work around this, you can resort to <firstterm>cross-instrumentation</firstterm>. Cross-instrumentation is the process of compiling a kernel module (out of a SystemTap script) to be used on a different machine. This process offers the following benefits: + </para> + + <itemizedlist> + <listitem><para>The debug RPMs for all target machines can be installed into one system: the host machine.</para></listitem> + + <listitem><para>Each target machine only needs one RPM to load and use the compiled kernel module: <filename>systemtap-runtime</filename>.</para></listitem> + + <listitem><para>You do not need to restart any of the target machines.</para></listitem> + </itemizedlist> + +<!-- + + <para> + Such a task does not scale well as the number of systems you are monitoring increases. As such, if you need to run a SystemTap script against a wide number of machines, you can simplify your deployment and monitoring through <firstterm>cross-instrumentation</firstterm>. + </para> + + <para> + <firstterm>Cross-instrumentation</firstterm> is the process of building the resulting kernel module from a SystemTap script on a <emphasis>host</emphasis> machine to be loaded on another <emphasis>target machine</emphasis>. In a manner of speaking, this process allows you to "run" SystemTap scripts on a machine without having to install the necessary debug RPMs for its kernel. + </para> + + + <para> + To illustrate; Tom has 25 systems, all of which have the same kernel. If Tom wants to run the SystemTap <filename>script.stp</filename> on all of them, he could install SystemTap and the necessary debug RPMs <emphasis>on each of the 25 machines</emphasis>. This is a tedious enough task to perform on 25 systems; what more if each system had a different kernel? + </para> + Alternatively, however, Tom can simply perform cross-instrumentation; this allows him to simply deploy SystemTap fully on one machine, build the necessary kernel module from <filename>script.stp</filename> on that machine, and load that module on each of the other systems. + </para> + + --> +<note> +<title>Note</title> +<para>For the sake of simplicity, we will be using the following terms throughout this section:</para> + +<itemizedlist> + <listitem><para><emphasis>instrumentation module</emphasis> — the kernel module built from a SystemTap script; i.e. the <emphasis>SystemTap module</emphasis> is built on the <emphasis>host system</emphasis>, and will be loaded on the <emphasis>target kernel</emphasis> of <emphasis>target system</emphasis>.</para></listitem> + + <listitem><para><emphasis>host system</emphasis> — the system on which you compile the kernel modules (from SystemTap scripts), to be loaded on <emphasis>target systems</emphasis>.</para></listitem> + + <listitem><para><emphasis>target system</emphasis> — the system for which you are building the <emphasis>instrumentation module</emphasis> (from SystemTap scripts).</para></listitem> + + <listitem><para><emphasis>target kernel</emphasis> — the kernel of the <emphasis>target system</emphasis>. This is the kernel on which you wish to load/run the <emphasis>instrumentation module</emphasis>.</para></listitem> +</itemizedlist> +</note> + +<!-- + running a SystemTap script on a target system where SystemTap is not installed. Normally, to run a SystemTap script on a system, you need to deploy SystemTap on it first (as in <xref linkend="installproper"/>). + </para> --> + +<!-- <para> + This section teaches you how to deploy SystemTap on a host machine, from which you can create the necessary kernel module/s to be loaded on client machines. These kernel modules are built from SystemTap scripts you wish to run on the client machine. + </para>--> + +<procedure id="preppingxcompile"> + <title>Configuring a Host System and Target Systems</title> + +<step> + <para>Configure <command>yum</command> on the <emphasis>host system</emphasis> to point to a repository containing the necessary debug RPMs for the <emphasis>target kernels</emphasis>. The following <command>yum</command> repository file (which you can add to <filename>/etc/yum.repos.d/</filename> points to a popular debug RPM repository for Red Hat Enterprise Linux 5:</para> +<screen> +[rhel-debuginfo] +name=Red Hat Enterprise Linux $releasever - $basearch - Debug + +baseurl=ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/ +enabled=1 +</screen> + </step> + + <step> + <para>Deploy SystemTap on the <emphasis>host system</emphasis>. It is from this machine that you will be building the <emphasis>instrumentation module</emphasis> (to be used on <emphasis>target systems</emphasis>). For instructions on how to deploy SystemTap, refer to <xref linkend="installproper"/>.</para> + </step> + + <step> + <para>Install the <emphasis>target kernel</emphasis> on the <emphasis>host system</emphasis>. If multiple <emphasis>target systems</emphasis> use different <emphasis>target kernel</emphasis>, you will need to install each <emphasis>target kernel</emphasis>.</para> + </step> + + <step> + <para> + Install the corresponding debug RPMs for the <emphasis>target kernel</emphasis> of each <emphasis>target system</emphasis> on the <emphasis>host system</emphasis>. + </para> + </step> + <step> + <para>Install <filename>yum-utils</filename> on the <emphasis>host system</emphasis>.</para> + </step> + + <step> + <para>Install <filename>systemtap-runtime</filename> on each <emphasis>target system</emphasis>.</para> + </step> +</procedure> + +<para>After performing <xref linkend="preppingxcompile"/>, you can now build the <emphasis>instrumentation module</emphasis> (for any <emphasis>target system</emphasis>) on the <emphasis>host system</emphasis>. </para> + +<para>To build the <emphasis>instrumentation module</emphasis>, run the following command on the <emphasis>host system</emphasis> (be sure to specify the appropriate values):</para> + +<para><command>stap -r <replaceable>[kernel version]</replaceable> <replaceable>[script]</replaceable> -m <replaceable>[module name]</replaceable></command></para> + +<para>Here, <command><replaceable>[kernel version]</replaceable></command> refers to the version of <emphasis>target kernel</emphasis> (including the architecture notation), <command><replaceable>[script]</replaceable></command> refers to the script to be converted into an <emphasis>instrumentation module</emphasis>, and <command><replaceable>[instrumentation name]</replaceable></command> is the desired name of the <emphasis>instrumentation module</emphasis>.</para> + +<note> + <title>Note</title> + <para>To determine the version of a running kernel, run <command>uname -r</command>. To determine the architecture notation of a running kernel, run <command>uname -m</command>.</para> +</note> + +<para>Once the the <emphasis>instrumentation module</emphasis>is compiled, copy it to the <emphasis>target system</emphasis> and load it using:</para> + +<para><command>staprun <replaceable>[instrumentation]</replaceable></command></para> + +<para> + For example, to create the <emphasis>instrumentation module</emphasis> <filename>module.ko</filename> from the SystemTap script <filename>script.stp</filename> for the <emphasis>target kernel</emphasis> 2.6.25.9-76.fc9 (on i686 architecture), use the following command: +</para> + +<para><command>stap -r 2.6.25.9-76.fc9.x86_64 script.stp -m module</command></para> + +<para>This will create a module named <filename>module.ko</filename>. To use the <emphasis>instrumentation module</emphasis> <filename>module.ko</filename>, copy it to the <emphasis>target system</emphasis> and run the following command (on the <emphasis>target system</emphasis>):</para> + +<para><command>staprun module.ko</command></para> + +<!--<procedure id="preppingxcompile"> + <title>Preparing for a Cross-Compile</title> + +<step> + <para>Note the version of the target system's kernel on which you wish to use SystemTap. You can do this by logging onto the target system and running <command>uname -r</command> (assuming the system is running the kernel on which you wish to use SystemTap), or by inspecting <filename>/boot</filename>.</para> +</step> --> + + + </section>
\ No newline at end of file diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index bbd265c2..160597bf 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -45,7 +45,7 @@ probe <replaceable>[event]</replaceable>, exit() } </programlisting> - <para>The <replaceable>exit()</replaceable> condition is optional, but it is recommended since it safely terminates the session once the script successfully traps the required information.</para> + <para>The <replaceable>exit()</replaceable> condition is optional; this condition safely terminates the session once the script successfully traps the required information the first time.</para> <important> <title>Important</title> @@ -56,29 +56,19 @@ probe <replaceable>[event]</replaceable>, <section id="systemtapscript-events"> <title>Events</title> -<para> - SystemTap supports multiple events per probe; as shown in <xref linkend="scriptformats"/>, multiple events are delimited by a comma (<command>,</command>). Sample <replaceable>[event]</replaceable>s include:</para> +<para>SystemTap events can be broadly classified into two types: <firstterm>synchronous</firstterm> and <firstterm>asynchronous</firstterm>.</para> -<variablelist> - -<varlistentry> - <term>begin</term> - <listitem> - <para>The startup of a SystemTap session; i.e. as soon as the SystemTap script is run.</para> - </listitem> -</varlistentry> +<formalpara><title>Synchronous Events</title> + <para>A <firstterm>synchronous</firstterm> event occurs when any processor executes an instruction matched by the specification. This gives other events a reference point (or instruction address) from which more contextual data may be available.</para> +</formalpara> -<varlistentry> - <term>end</term> - <listitem> - <para>The end of a SystemTap session.</para> - </listitem> -</varlistentry> +<para>Examples of synchronous events include:</para> +<variablelist> <varlistentry> <term>kernel.function("<replaceable>[function]</replaceable>")</term> <listitem> - <para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that the kernel function <command>sys_open</command> is used. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para> + <para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that occurs when the kernel function <command>sys_open</command> is called by any thread in the system. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para> <para>When defining functions, you can use asterisk (<command>*</command>) for wildcards. You can also trace the entry/exit of a function in a kernel source file. Consider the following example:</para> <example id="wildcards"><title>Wildcards and Kernel Source Files in an Event</title> @@ -100,9 +90,59 @@ probe kernel.function("*@net/socket.c").return { } <para>To identify what system calls are made by a specific program/command, use <command>strace <replaceable>command</replaceable></command>.</para> </listitem> </varlistentry> + +<varlistentry> + <term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term> + <listitem> + <para>Allows you to probe functions within modules. For example:</para> + + <example id="eventsmodules"><title>Module Probe</title> + <programlisting> + probe module("ext3").function("*") { } + probe module("ext3").function("*").return { } + </programlisting> + </example> + + <para> + The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). + </para> + + <para> + A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. + </para> + + </listitem> +</varlistentry> +</variablelist> + + +<formalpara> + <title>Asynchronous Events</title> + <para><firstterm>Asynchronous</firstterm> events, on the other hand, do not point to any reference point. This family of probe points consists mainly of counters, timers, and similar constructs.</para> +</formalpara> + <para>Examples of asynchronous events include:</para> + +<variablelist> + <varlistentry> - <term>timer.ms()</term> + <term>begin</term> + <listitem> + <para>The startup of a SystemTap session; i.e. as soon as the SystemTap script is run.</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>end</term> + <listitem> + <para>The end of a SystemTap session.</para> + </listitem> +</varlistentry> + + + +<varlistentry> + <term>timer events</term> <listitem> <para>An event that specifies a handler to be executed "after X number of milliseconds". For example:</para> @@ -116,34 +156,29 @@ probe timer.ms(4000) </example> <para> - <xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds (or 4 seconds). When used in conjunction with another probe that traps a large quantity of data, a probe using <command>timer.ms()</command> allows you to limit the information your script is collecting (and printing out). + <xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds. Note that you can also use the following timer events: +</para> + +<itemizedlist> +<listitem><para><command>timer.s(<replaceable>[seconds]</replaceable>)</command></para></listitem> + +<listitem><para><command>timer.us(<replaceable>[microseconds]</replaceable>)</command></para></listitem> + +<listitem><para><command>timer.ns(<replaceable>[nanoseconds]</replaceable>)</command></para></listitem> + +<listitem><para><command>timer.hz(<replaceable>[hertz]</replaceable>)</command></para></listitem> + +<listitem><para><command>timer.jiffies(<replaceable>[jiffies]</replaceable>)</command></para></listitem> + +</itemizedlist> +<para> + When used in conjunction with another probe that traps a large quantity of data, timer events allow you to limit the information your script is collecting (and printing out). </para> </listitem> </varlistentry> -<varlistentry> - <term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term> - <listitem> - <para>Allows you to probe functions within modules. For example:</para> - -<example id="eventsmodules"><title>Module Probe</title> -<programlisting> -probe module("ext3").function("*") { }
-probe module("ext3").function("*").return { } -</programlisting> -</example> - <para> - The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). - </para> - - <para> - A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. - </para> - - </listitem> -</varlistentry> <!--<remark>add timer.ms() to events list!</remark>--> <!-- @@ -164,7 +199,12 @@ probe module("ext3").function("*").return { } </para> </important> +<para> + SystemTap supports multiple events per probe; as shown in <xref linkend="scriptformats"/>, multiple events are delimited by a comma (<command>,</command>). If multiple events are specified in a single probe, SystemTap will execute the handler when any of the specified events occur. +</para> + <remark>is reference appropriate? too advanced for readers (it seems so to me)? please advise.</remark> + </section> <section id="systemtapscript-handlers"> @@ -191,11 +231,10 @@ probe begin <formalpara id="printf"> <title>printf ( ) Statements</title> <para> - The <command>printf ()</command> statement is one of the simplest handler tools for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format: + The <command>printf ()</command> statement is one of the simplest functions for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format: </para> </formalpara> -<remark>is "handler tool" appropriate?</remark> <programlisting> @@ -210,6 +249,11 @@ printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]< You can use the variables <command>%s</command> (for strings) and <command>%d</command> (for numbers) in format strings, depending on your list of arguments. Format strings can have multiple variables, each matching a corresponding argument; multiple arguments are delimited by a comma (<command>,</command>) and space. </para> +<note> + <title>Note</title> + <para>Semantically, the SystemTap <command>printf</command> function is very similar to its C language counterpart. The aforementioned syntax and format for SystemTap's <command>printf</command> function is identical to that of the C-style <command>printf</command>.</para> +</note> + <para> To illustrate this, consider the following probe example: </para> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml b/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml index 662d5b3d..0377c499 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml @@ -7,5 +7,8 @@ <remark>This chapter covers miscellaneous tips/tricks</remark> <remark>This is a tentative section, and will only be included if content can be provided</remark> + + + </chapter> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml index 76296507..2794901c 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml @@ -30,9 +30,12 @@ <para>A SystemTap session begins when you run a SystemTap script. This session occurs in the following fashion:</para> -<procedure> +<procedure id="systemtapsession"> <title>SystemTap Session</title> - <step><para>SystemTap first translates the script to C, running the system C compiler to create a kernel module from it.</para></step> + + <step><para>First, SystemTap checks the script against the existing tapset library (normally in <filename>/usr/share/systemtap/tapset/</filename> for any tapsets used.</para></step> + + <step><para>SystemTap then translates the script to C, running the system C compiler to create a kernel module from it.</para></step> <step><para>SystemTap loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step> @@ -59,7 +62,34 @@ <remark> definition, significance, difference with stap scripts (previous section), library of tapsets in system: location - </remark> + </remark> + + <para> + <firstterm>Tapsets</firstterm> are scripts that form a library of pre-written probes and functions to be used in SystemTap scripts. When a user runs a SystemTap script, SystemTap checks the script's probe events and handlers against the tapset library; SystemTap then loads the corresponding probes and functions before translating the script to C (refer to <xref linkend="understanding-architecture-tools"/> for information on what transpires in a SystemTap session). + </para> +<!-- + <para> + Simply put, the tapset library is an abstraction layer designed to make it easier for users to define events and functions. In a way, tapsets provide useful "aliases" for functions that users may want to specify as an event; knowing the proper alias to use is, for the most part, easier than understanding how to specify a specific kernel function. + </para> + --> + <para> + Like SystemTap scripts, tapsets use the filename extension <filename>.stp</filename>. The standard library of tapsets is located in <filename>/usr/share/systemtap/tapset/</filename> by default. However, unlike SystemTap scripts, tapsets are not meant for direct execution; rather, they constitute the library from which other scripts can pull definitions. + </para> + + + <para> + Simply put, the tapset library is an abstraction layer designed to make it easier for users to define events and functions. In a manner of speaking, tapsets provide useful "aliases" for functions that users may want to specify as an event; knowing the proper alias to use is, for the most part, easier than understanding how to specify a specific kernel function. + </para> + + <para> + Several handlers and functions in <xref linkend="systemtapscript-events"/> and <xref linkend="systemtapscript-handlers"/> are defined in tapsets. For example, <command>thread_indent()</command> is defined in <filename>indent.stp</filename>. + </para> + + +<remark> + any other details to be included? i dont want to dwell too long here, though, since IMHO tapset development is beyond the scope of this "beginner's guide" +</remark> + </section> </chapter> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml new file mode 100644 index 00000000..df6477de --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml @@ -0,0 +1,212 @@ +<?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="useful-disk-disktop"> + <title>Summarizing Disk Read/Write Traffic</title> + + + <remark> + NO ENTRY IN WAR STORIES: Summarize Disk Read/Write Traffic + http://sourceware.org/systemtap/examples/io/disktop.stp + </remark> + + + <para>This section describes how to identify which processes are performing the heaviest disk reads/writes to the system.</para> + +<formalpara id="scriptdisktop"> + <title>disktop.stp</title> +<para> +<programlisting> +#!/usr/bin/env stap +# +# Copyright (C) 2007 Oracle Corp. +# +# Get the status of reading/writing disk every 5 seconds, output top ten entries +# +# This is free software,GNU General Public License (GPL); either version 2, or (at your option) any +# later version. +# +# Usage: +# ./disktop.stp +# + +global io_stat,device +global read_bytes,write_bytes + +probe kernel.function("vfs_read").return { + if ($return>0) { + dev = __file_dev($file) + devname = __find_bdevname(dev,__file_bdev($file)) + + if (devname!="N/A") {/*skip read from cache*/ + io_stat[pid(),execname(),uid(),ppid(),"R"] += $return + device[pid(),execname(),uid(),ppid(),"R"] = devname + read_bytes += $return + } + } +} + +probe kernel.function("vfs_write").return { + if ($return>0) { + dev = __file_dev($file) + devname = __find_bdevname(dev,__file_bdev($file)) + + if (devname!="N/A") { /*skip update cache*/ + io_stat[pid(),execname(),uid(),ppid(),"W"] += $return + device[pid(),execname(),uid(),ppid(),"W"] = devname + write_bytes += $return + } + } +} + +probe timer.ms(5000) { + /* skip non-read/write disk */ + if (read_bytes+write_bytes) { + + printf("\n%-25s, %-8s%4dKb/sec, %-7s%6dKb, %-7s%6dKb\n\n",ctime(gettimeofday_s()),"Average:", + ((read_bytes+write_bytes)/1024)/5,"Read:",read_bytes/1024,"Write:",write_bytes/1024) + + /* print header */ + printf("%8s %8s %8s %25s %8s %4s %12s\n","UID","PID","PPID","CMD","DEVICE","T","BYTES") + } + /* print top ten I/O */ + foreach ([process,cmd,userid,parent,action] in io_stat- limit 10) + printf("%8d %8d %8d %25s %8s %4s %12d\n",userid,process,parent,cmd,device[process,cmd,userid,parent,action],action,io_stat[process,cmd,userid,parent,action]) + + /* clear data */ + delete io_stat + delete device + read_bytes = 0 + write_bytes = 0 +} + +probe end{ + delete io_stat + delete device + delete read_bytes + delete write_bytes +} +</programlisting> +</para> +</formalpara> + +<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> — user ID. A user ID of <command>0</command> refers to the root user.</para></listitem> + + <listitem><para><command>PID</command> — the ID of the listed process.</para></listitem> + + <listitem><para><command>PPID</command> — the process ID of the listed process's <emphasis>parent process</emphasis>.</para></listitem> + + <listitem><para><command>CMD</command> — the name of the listed process.</para></listitem> + + <listitem><para><command>DEVICE</command> — which storage device the listed process is reading from or writing to.</para></listitem> + + <listitem><para><command>T</command> — 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><command>BYTES</command> — the amount of data read to or written from disk.</para></listitem> +</itemizedlist> + + +<example id="disktopoutput"> + <title><xref linkend="scriptdisktop"/> Sample Output</title> +<screen> +[...] +Mon Sep 29 03:38:28 2008 , Average: 19Kb/sec, Read: 7Kb, Write: 89Kb
+ +UID PID PPID CMD DEVICE T BYTES
+0 26319 26294 firefox sda5 W 90229
+0 2758 2757 pam_timestamp_c sda5 R 8064
+0 2885 1 cupsd sda5 W 1678
+ +Mon Sep 29 03:38:38 2008 , Average: 1Kb/sec, Read: 7Kb, Write: 1Kb
+ +UID PID PPID CMD DEVICE T BYTES
+0 2758 2757 pam_timestamp_c sda5 R 8064
+0 2885 1 cupsd sda5 W 1678
+</screen> +</example> + +<para> + + + + + + + + + +<para><xref linkend="scriptdiskusage"/> outputs raw statistics on both CPU and disk usage per second. I/O usage is tracked through the events <command>ioblock.request</command> and <command>ioblock.request.end</command>, which track each request (and request completion) for a generic block I/O. CPU usage is tracked through <command>scheduler.cpu_on</command> and <command>scheduler.cpu_off</command>, which are activated whenever a process begins (and ends) a command execution on a CPU.</para> + +<section id="gnuplotexplain"> + <title>gnuplot</title> +<para>Running <xref linkend="scriptdiskusage"/> by itself hardly presents any data that is useful, as in <xref linkend="rawdiskusagegraph"/>.</para> + +<example id="rawdiskusagegraph"><title>Raw disk-usage-graph.stp Output</title> +<screen> +[...] +62 +5 +3 +4 +6 +4 +4 +5 +5 +3 +6 +5 +e +pause 1 +</screen> +</example> + +<para>However, refining the output of <xref linkend="scriptdiskusage"/> through <command>gnuplot</command> presents us with a more useful result. <command>gnuplot</command> is a lightweight, command-line driven plotting program that helps you display data in a graphical format.</para> + +<para>By piping <xref linkend="scriptdiskusage"/> output to <command>gnuplot</command> (as in <command>stap disk-usage-graph.stp | gnuplot</command>), we get a graphical output similar to the following:</para> + +<figure id="gnuoutputsample"> + <title>Graphical Output Sample</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/gnuplotsample.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Sample output</phrase> + </textobject> + <caption> + <para> + Sample output of <xref linkend="scriptdiskusage"/> when piped through <command>gnuplot</command> + </para> + </caption> +</mediaobject> +</figure> + +<para><xref linkend="gnuoutputsample"/> presents a cleaner, more useful graphical output. This graph can show you the level of utilization for both I/O and CPU, in real time.</para> + +<remark> + question: does this script also capture stap process? i.e. does the graph also include CPU utilization by systemtap while the script is running? +</remark> + + + <remark> + http://sourceware.org/systemtap/examples/subsystem-index.html + </remark> + + <remark> + Graphing Disk and CPU Utilization - http://sourceware.org/systemtap/examples/general/graphs.stp + </remark> + + + <remark> + Summarize Disk Read/Write Traffic + http://sourceware.org/systemtap/examples/io/disktop.stp + </remark> + </section> + </section> + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index f3f7a276..30c8500f 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -7,30 +7,161 @@ <remark> short intro, contents of chapter </remark> + + <para> + This chapter instructs users how to install SystemTap, and provides an introduction on how to run SystemTap scripts. + </para> + <section id="using-setup"> <title>Setup and Installation</title> <remark> required packages, installation thru yum, repos (?); possibly, a script to install all required packages </remark> + + <remark> + notes in ~/Desktop/SystemTap/aug21chatlog and ~/Desktop/SystemTap/noted_wcohenmeeting + </remark> + + <para> + To deploy SystemTap, you need to install the SystemTap packages along with the corresponding set of debug RPMs of your kernel. This means that if your system has multiple kernels installed, and you wish to use SystemTap on more than one kernel, you will need to install the debug RPMs for <emphasis>each</emphasis> of those kernels. + </para> <formalpara> - <title>Cross-Compiling</title> - <para>TBD</para> -</formalpara> -<remark>above; add short description, significance, howto, script (test first)</remark> + <title>Preparing For Installation</title> + <para> + To view what kernels and kernel versions are installed on your system, check the contents of <filename>/boot</filename>. Each installed kernel/kernel version has a corresponding <filename>vmlinuz-<replaceable>[kernel version]</replaceable></filename> there. + </para> +</formalpara> + <para> + To determine what kernel your system is currently using, use: + </para> - </section> +<screen> +uname -r +</screen> + + <para> + You will also need to configure <command>yum</command> to point to a repository that houses the necessary debug RPMs. One such repository is: + </para> + + <para><ulink url=" ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/"/></para> + + <remark>find any other such repository, if only for RHEL</remark> + + +<procedure id="installproper"> + <title>Deploying SystemTap</title> + +<step> + <para>Once you've decided which kernels you need to use SystemTap with, install the following packages:</para> + <itemizedlist> + <listitem><para><filename>systemtap</filename></para></listitem> + <listitem><para><filename>systemtap-runtime</filename></para></listitem> + </itemizedlist> + + <para>This will install the SystemTap suite of tools.</para> +</step> + +<step> + <para>Next, you'll need to download and install the necessary debug RPMs for your kernel. Most debugging RPMs for Red Hat Enterprise Linux 5 can be found at the following link:</para> + + <para>The necessary debugging RPMs are as follows:</para> + +<itemizedlist> + <listitem><para><filename>kernel-debuginfo</filename></para></listitem> + <listitem><para><filename>kernel-debuginfo-common</filename></para></listitem> + <listitem><para><filename>kernel-devel</filename></para></listitem> +</itemizedlist> + +<para>For example, if you wish to use SystemTap on kernel version <filename>2.6.18-53.el5</filename>, then you need to download the following debugging RPMs:</para> + +<example id="debuggingrpmlist"> + <title>Sample List of Debugging RPMs</title> +<itemizedlist> + <listitem><para><filename>kernel-debuginfo-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem> + <listitem><para><filename>kernel-debuginfo-common-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem> + <listitem><para><filename>kernel-devel-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem> +</itemizedlist> +</example> +</step> + +<step> + <para>Install the debugging RPMs using <command>rpm -ivh <replaceable>[RPM]</replaceable></command> or <command>yum localinstall <replaceable>[RPM]</replaceable></command>.</para> +</step> + +<step> + <para> + Restart the system, loading the appropriate kernel at the <command>grub</command> screen. + </para> +</step> +</procedure> + + +<!-- +<itemizedlist> + <listitem><para><filename>systemtap</filename></para></listitem> + <listitem><para><filename>systemtap-runtime</filename></para></listitem> +</itemizedlist> + --> + </section> + <xi:include href="CrossInstrumenting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <section id="using-usage"> <title>Usage</title> <remark> - basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter) + - basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter) </remark> <remark> - running systemtap scripts + - running systemtap scripts </remark> +<!-- + <remark>- Tapsets: short intro on usage</remark> + --> + <para> + SystemTap scripts are run through the command <command>stap</command>. <command>stap</command> can run SystemTap scripts from standard input or from file. Below is a list of common options available to you: + </para> + +<variablelist> + +<varlistentry> + <term>-v</term> + <listitem> + <para>Makes the output of the SystemTap session more verbose. You can repeat this option to (for example, <command>stap -vvv script.stp</command>); provide more details on the script's execution. This option is particularly useful if you encounter any errors in running the script.</para> - <remark>Tapsets: short intro on usage</remark> + <para>For more information about common SystemTap script errors, refer to <xref linkend="errors"/>.</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>-I <replaceable>[directory]</replaceable></term> + <listitem> + <para>Check the script against additional tapsets found in <command><replaceable>[directory]</replaceable></command>. This is useful if you have additional tapsets that are not included in <filename>/usr/share/systemtap/tapset/</filename>; for more information about tapsets, refer to <xref linkend="understanding-tapsets"/>.</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>-o <replaceable>[filename]</replaceable></term> + <listitem> + <para>Sends the standard output to file (<replaceable>[filename]</replaceable>).</para> + </listitem> +</varlistentry> + +<!-- +<varlistentry> + <term></term> + <listitem> + <para></para> + </listitem> +</varlistentry> + --> +</variablelist> + +<remark>any other useful options worth noting here for beginners?</remark> + +<para>For more information about <command>stap</command>, refer to <command>man stap</command>.</para> + +<para>To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use <command>staprun</command> instead. For more information about <command>staprun</command> and cross-instrumentation, refer to <xref linkend="cross-compiling"/>.</para> + </section> </chapter> diff --git a/doc/SystemTap_Beginners_Guide/en-US/images/gnuplotsample.png b/doc/SystemTap_Beginners_Guide/en-US/images/gnuplotsample.png Binary files differnew file mode 100755 index 00000000..c84bbd57 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/images/gnuplotsample.png |
