diff options
11 files changed, 582 insertions, 16 deletions
diff --git a/doc/SystemTap_Beginners_Guide/Makefile b/doc/SystemTap_Beginners_Guide/Makefile index 0d8b4546..32135688 100644 --- a/doc/SystemTap_Beginners_Guide/Makefile +++ b/doc/SystemTap_Beginners_Guide/Makefile @@ -6,6 +6,8 @@ BRAND = RedHat #OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW +CONDITION=$(BRAND) + COMMON_CONFIG = /usr/share/publican include $(COMMON_CONFIG)/make/Makefile.common diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index b928372b..7914e79c 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -76,7 +76,7 @@ probe <replaceable>event</replaceable>, <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 (<literal>*</literal>) for wildcards. You can also trace the entry or 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> +<example id="wildcards"><title>wildcards.stp</title> <programlisting> probe kernel.function("*@net/socket.c") { } probe kernel.function("*@net/socket.c").return { } @@ -101,11 +101,11 @@ probe kernel.function("*@net/socket.c").return { } <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 id="eventsmodules"><title>moduleprobe.stp</title> +<programlisting> +probe module("ext3").function("*") { } +probe module("ext3").function("*").return { } +</programlisting> </example> <para> @@ -152,7 +152,7 @@ probe kernel.function("*@net/socket.c").return { } <listitem> <para>An event that specifies a handler to be executed every specified period of time. For example:</para> -<example id="timer"><title>Using timer.ms</title> +<example id="timer"><title>timer-ms.stp</title> <programlisting> probe timer.ms(4000) { @@ -224,7 +224,7 @@ probe timer.ms(4000) Consider the following sample script: </para> -<example id="helloworld"><title>Hello World</title> +<example id="helloworld"><title>helloworld.stp</title> <programlisting> probe begin { @@ -269,7 +269,7 @@ printf ("<replaceable>format string</replaceable>\n", <replaceable>argument</rep </para> <example id="syscall-open"> - <title>Using Variables In printf ( ) Statements</title> + <title>variables-in-printf-statements.stp</title> <programlisting> # This probe will need to be manually terminated with Ctrl-C probe syscall.open @@ -368,7 +368,7 @@ hald(2360) open Consider the following example on the use of <command>thread_indent()</command>: </para> -<example id="thread_indent"><title>Using thread_indent()</title> +<example id="thread_indent"><title>thread_indent.stp</title> <programlisting> probe kernel.function("*@net/socket.c") { @@ -405,6 +405,41 @@ probe kernel.function("*@net/socket.c").return </listitem> </varlistentry> + +<varlistentry> + <term>name</term> + <listitem> + <para>Identifies the name of a specific system call.</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>target()</term> + <listitem> + <para>Used in conjunction with <command>stap <replaceable>script</replaceable> -x <replaceable>process ID</replaceable></command> or <command>stap <replaceable>script</replaceable> -c <replaceable>command</replaceable></command>. If you want to specify a script to take an argument of a process ID or command, use <command>target()</command> as the variable in the script to refer to it. For example:</para> + +<example id="targetexample"> + <title>targetexample.stp</title> +<programlisting> +probe syscall.* { + if (pid() == target()) { + printf("%s/n", name) + }} +</programlisting> +</example> + + <para>When <xref linkend="targetexample"/> is run with the argument <command>-x <replaceable>process ID</replaceable></command>, it watches all system calls (as specified by the event <command>syscall.*</command>) and prints out the name of all system calls made by the specified process.</para> + + <para>This has the same effect as specifying <command>if (pid() == <replaceable>process ID</replaceable></command> each time you wish to target a specific process. However, using <command>target()</command> makes it easier for you to re-use the script, giving you the ability to simply pass a process ID as an argument each time you wish to run the script (e.g. <command>stap targetexample.stp -x <replaceable>process ID</replaceable></command>).</para> +<!-- +<note> + <title>Note</title> + <para>In <xref linkend="targetexample"/>, <command>name</command> instructs SystemTap to capture the name of the process</para> +</note> --> + + </listitem> +</varlistentry> + <!-- <varlistentry> <term></term> @@ -437,7 +472,125 @@ probe kernel.function("*@net/socket.c").return </section> + <section id="handlerconditionals"> + <title>Basic Handler Constructs</title> + +<para>SystemTap supports the use of several basic constructs in handlers. The syntax for most of these handler constructs are mostly based on C and <command>awk</command> syntax. This section describes several of the most useful SystemTap handler constructs.</para> + +<formalpara id="variablesconstructs"> + <title>Variables</title> + + <para>Variables can be used freely throughout a handler; simply choose a name, assign it to a function, and use it in an expression. SystemTap automatically identifies whether a variable should be identified as a string or integer, based on the function it is assigned to. For instance, if you use set the variable <command>foo</command> to <command>gettimeofday_s()</command> (as in <command>foo = gettimeofday_s()</command>), then <command>foo</command> can be used as an integer argument (<command>%d</command>) in <command>printf()</command>.</para> +</formalpara> + +<para>Note, however, that by default variables are only local to the probe they are used in. This means that variables are initialized, used and disposed at each probe handler invocation. To share a variable between probes, declare the variable name first using <command>global</command> outside of any probe. Consider the following example:</para> + +<example id="timerjiffies"> + <title>timer-jiffies.stp</title> +<programlisting> +global count_jiffies, count_ms +probe timer.jiffies(100) { count_jiffies ++ } +probe timer.ms(100) { count_ms ++ } +probe timer.ms(12345) +{ + hz=(1000*count_jiffies) / count_ms + printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n", + count_jiffies, count_ms, hz) + exit () +} +</programlisting> +</example> + +<para><xref linkend="timerjiffies"/> attempts to compute the <command>CONFIG_HZ</command> setting of the kernel using timers that count jiffies and milliseconds, then computing accordingly. The <command>global</command> statement allows the script to use the variables <command>count_jiffies</command> and <command>count_ms</command> (set in their own respective probes) to be shared with <command>probe timer.ms(12345)</command>.</para> + +<note> + <title>Note</title> + <para>In some cases, such as in <xref linkend="timerjiffies"/>, a variable may be declared without any specific value as yet. You need to declare such values as integers using the notation <command>++</command>.</para> +</note> + + + +<formalpara> + <title>Conditional Statements</title> +<para> +In some cases, the output of a SystemTap script may be too big. To address this, you need to further refine the script's logic in order to delimit the output into something more relevant or useful to your probe. +</para> +</formalpara> +<para> +You can do this by using <emphasis>conditionals</emphasis> in handlers. SystemTap accepts the following types of conditional statements: +</para> + +<variablelist> +<varlistentry> + <term>If/Else Statements</term> + <listitem> + <para>Format:</para> +<programlisting> +{ +if (<replaceable>condition</replaceable>) + {<replaceable>handler</replaceable>} [else {<replaceable>handler</replaceable>}] +} +</programlisting> + </listitem> +</varlistentry> + +<varlistentry> + <term>While Loops</term> + <listitem> + <para>Format:</para> +<programlisting> +{ +while (<replaceable>condition</replaceable>) {<replaceable>handler</replaceable>} +} +</programlisting> + </listitem> +</varlistentry> + +<varlistentry> + <term>For Loops</term> + <listitem> + <para>Format:</para> +<programlisting> +{ +for (<replaceable>argument1</replaceable>; <replaceable>argument2</replaceable>; <replaceable>argument3</replaceable>) {<replaceable>handler</replaceable>} +} +</programlisting> + </listitem> +</varlistentry> + +<!--<para>Each conditional statement must be enclosed in <command>{ }</command>.</para>--> +<!-- +<varlistentry> + <term></term> + <listitem> + <para></para> + </listitem> +</varlistentry> +--> + +</variablelist> + +<para>These constructs are better illustrated in the different examples available in <xref linkend="useful-systemtap-scripts"/>.</para> + +<remark>will get back to these ones later</remark> + +<formalpara> + <title>Command-Line Arguments</title> + <para>You can also allow a SystemTap script to accept simple command-line arguments and declare them in the script without using <command>target()</command>. One way to do this is to use the variable notation <command>$</command> or <command>@</command>.</para> +</formalpara> + + +<example id="commandlineargs"><title>commandlineargs.stp</title> +<programlisting> +probe kernel.function(@1) { } +probe kernel.function(@1).return { } +</programlisting> +</example> + +<para><xref linkend="commandlineargs"/> is similar to <xref linkend="wildcards"/>, except that it allows you to pass the kernel function to be probed as a command-line argument (as in <command>stap commandlineargs.stp <replaceable>kernel function</replaceable></command>). You can also specify the script to accept multiple command-line arguments, noting them as <command>@1</command>, <command>@2</command>, and so on, in the order they are entered by the user.</para> + + </section> <!-- <section id="SystemTap_Beginners_Guide-Test-Section_2_Test"> <title>Section 2 Test</title> <para> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Section.xml b/doc/SystemTap_Beginners_Guide/en-US/Section.xml new file mode 100644 index 00000000..c5895624 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Section.xml @@ -0,0 +1,12 @@ +<?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="SystemTap_Beginners_Guide-Test-Section_1_Test"> + <title>Section 1 Test</title> + <para> + Test of a section + </para> + </section> + + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml new file mode 100644 index 00000000..96e58bb4 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml @@ -0,0 +1,71 @@ +<?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="inodewatchsect"> + <title>Monitoring Reads and Writes to a File</title> + + +<remark> +WAR STORY: monitoring inode activity http://sourceware.org/systemtap/wiki/WSFileMonitor?highlight=((WarStories)) +</remark> + +<remark> +no script in examples +</remark> + + + <para>This section describes how to monitor reads from and writes to a file in real time. </para> + +<formalpara id="inodewatch"> + <title>inodewatch.stp</title> +<para> +<programlisting> +probe kernel.function ("vfs_write"), + kernel.function ("vfs_read") +{ + dev_nr = $file->f_dentry->d_inode->i_sb->s_dev + inode_nr = $file->f_dentry->d_inode->i_ino + + if (dev_nr == ($1 << 20 | $2) # major/minor device + && inode_nr == $3) + printf ("%s(%d) %s 0x%x/%u\n", + execname(), pid(), probefunc(), dev_nr, inode_nr) +} +</programlisting> +</para> +</formalpara> + +<para><xref linkend="inodewatch"/> takes the following information about the file as an argument:</para> + +<itemizedlist> + <listitem><para>The file's device number, in integer format. When this is passed to the script as the first argument, be sure to replace any <computeroutput>0</computeroutput> with a space.</para></listitem> + + <listitem><para>The file's <command>inode</command> number.</para></listitem> +</itemizedlist> + +<para>To get this information, use <command>stat -c '%D %i' <replaceable>filename</replaceable></command>, where <command><replaceable>filename</replaceable></command> is an absolute path.</para> + +<para>For instance: if you wish to monitor <filename>/etc/crontab</filename>, run <command>stat -c '%D %i' /etc/crontab</command> first. This gives the following output:</para> + +<screen> +805 1078319 +</screen> + +<para><computeroutput>805</computeroutput> is the device number, while <computeroutput>1078319</computeroutput> is the <command>inode</command> number. To start monitoring <filename>/etc/crontab</filename>, run <command>stap inodewatch.stp 8 5 1078319</command>.</para> + +<para>The output of this command contains the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), the device number (in hex format), and the <command>inode</command> number. <xref linkend="inodewatchoutput"/> contains the output of <command>stap inodewatch.stp 8 5 1078319</command> (when <command>cat /etc/crontab</command> is executed while the script is running) :</para> + + +<example id="inodewatchoutput"> + <title><xref linkend="inodewatch"/> Sample Output</title> +<screen> +cat(16437) vfs_read 0x800005/1078319 +cat(16437) vfs_read 0x800005/1078319 +</screen> +</example> + + + </section> + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch2.xml new file mode 100644 index 00000000..300029cc --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch2.xml @@ -0,0 +1,57 @@ +<?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="inodewatch2sect"> + <title>Monitoring Changes to File Attributes</title> + + +<remark> + WAR STORY: monitoring more inode activity http://sourceware.org/systemtap/wiki/WSFileMonitor2?highlight=((WarStories)) +</remark> + +<remark> +no script in examples +</remark> + + + <para>This section describes how to monitor if any processes are changing the attributes of a targeted file, in real time. </para> + +<formalpara id="inodewatch2"> + <title>inodewatch2.stp</title> +<para> +<programlisting> +global ATTR_MODE = 1 # .... + +probe kernel.function("inode_setattr") { + dev_nr = $inode->i_sb->s_dev + inode_nr = $inode->i_ino + + if (dev_nr == ($1 << 20 | $2) # major/minor device + && inode_nr == $3 + && $attr->ia_valid & ATTR_MODE) + printf ("%s(%d) %s 0x%x/%u %o %d\n", + execname(), pid(), probefunc(), dev_nr, inode_nr, $attr->ia_mode, uid()) + } +</programlisting> +</para> +</formalpara> + +<para>Like <xref linkend="inodewatch"/> from <xref linkend="inodewatchsect"/>, <xref linkend="inodewatch2"/> takes the targeted file's device number (in integer format) and <command>inode</command> number as arguments. For more information on how to retrieve this information, refer to <xref linkend="inodewatchsect"/>.</para> + +<para>The output for <xref linkend="inodewatch2"/> is similar to that of <xref linkend="inodewatch"/>, except that <xref linkend="inodewatch2"/> also contains the attribute changes to the monitored file, as well as the ID of the user responsible (<command>uid()</command>). <xref linkend="inodewatch2output"/> contains shows the output of <xref linkend="inodewatch2"/> while monitoring <filename>/home/joe/bigfile</filename> when user <computeroutput>joe</computeroutput> executes <command>chmod 777 /home/joe/bigfile</command> and <command>chmod 666 /home/joe/bigfile</command>.</para> + + + +<example id="inodewatch2output"> + <title><xref linkend="inodewatch2"/> Sample Output</title> +<screen> +chmod(17448) inode_setattr 0x800005/6011835 100777 500 +chmod(17449) inode_setattr 0x800005/6011835 100666 500 +</screen> +</example> + + + </section> + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml index fe249428..42b9e025 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml @@ -72,5 +72,5 @@ probe timer.s(5) { </screen> </example> -<para><xref linkend="iotopoutput"/> displays top I/O writes and reads within a random 10-second interval. Note that <xref linkend="iotop"/> is recursive, as it also detects I/O resulting from SystemTap activity — <xref linkend="iotopoutput"/> also displays reads done by <command>staprun</command>.</para> +<para><xref linkend="iotopoutput"/> displays top I/O writes and reads within a random 10-second interval. Note that <xref linkend="iotop"/> also detects I/O resulting from SystemTap activity — <xref linkend="iotopoutput"/> also displays reads done by <command>staprun</command>.</para> </section>
\ No newline at end of file diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml new file mode 100644 index 00000000..3540a2c4 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml @@ -0,0 +1,99 @@ +<?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="paracallgraph"> + <title>Call Graph Tracing</title> + + + <remark> + WAR STORY: Call graph tracing http://sourceware.org/systemtap/wiki/WSCallGraph?highlight=((WarStories)) + </remark> + + <remark> + script: http://sourceware.org/systemtap/examples/general/para-callgraph.stp + </remark> + + + <para>This section describes how to trace incoming and outgoing function calls. </para> + +<formalpara id="scriptcallgraph"> + <title>para-callgraph.stp</title> +<para> +<programlisting> +function trace(entry_p) { + if(tid() in trace) + printf("%s%s%s\n",thread_indent(entry_p), + (entry_p>0?"->":"<-"), + probefunc()) +} + +global trace +probe kernel.function(@1).call { + if (execname() == "stapio") next # skip our own helper process + trace[tid()] = 1 + trace(1) +} +probe kernel.function(@1).return { + trace(-1) + delete trace[tid()] +} + +probe kernel.function(@2).call { trace(1) } +probe kernel.function(@2).return { trace(-1) } +</programlisting> +</para> +</formalpara> + +<para><xref linkend="scriptcallgraph"/> takes two command-line arguments:</para> + +<itemizedlist> + <listitem><para>A <firstterm>trigger function</firstterm> (<command>@1</command>), which enables or disables tracing on a per-thread basis.</para></listitem> + <listitem><para>The probe function whose entry/exit you'd like to trace (<command>@2</command>).</para></listitem> +</itemizedlist> + +<remark> please verify previous if correct; i'm particularly interested in finding out how to better describe "trigger function"</remark> + +<para><xref linkend="scriptcallgraph"/> uses <command>thread_indent()</command>; as such, its output contains the timestamp, process name, and thread ID of <command>@2</command> (i.e. the probe function you are tracing). For more information about <command>thread_indent()</command>, refer to its entry in <xref linkend="systemtapscript-handlers"/>.</para> + + <para>The following example contains an excerpt from the output for <command>stap para-callgraph.stp sys_read '*@fs/*.c'</command>:</para> + + +<example id="paracallgraphoutput"> + <title><xref linkend="scriptcallgraph"/> Sample Output</title> +<screen> +[...] + 0 klogd(1391):->sys_read + 14 klogd(1391): ->fget_light + 22 klogd(1391): <-fget_light + 27 klogd(1391): ->vfs_read + 35 klogd(1391): ->rw_verify_area + 43 klogd(1391): <-rw_verify_area + 49 klogd(1391): ->kmsg_read + 0 sendmail(1696):->sys_read + 17 sendmail(1696): ->fget_light + 26 sendmail(1696): <-fget_light + 34 sendmail(1696): ->vfs_read + 44 sendmail(1696): ->rw_verify_area + 52 sendmail(1696): <-rw_verify_area + 58 sendmail(1696): ->proc_file_read + 70 sendmail(1696): ->loadavg_read_proc + 84 sendmail(1696): ->proc_calc_metrics + 92 sendmail(1696): <-proc_calc_metrics + 95 sendmail(1696): <-loadavg_read_proc + 101 sendmail(1696): <-proc_file_read + 106 sendmail(1696): ->dnotify_parent + 115 sendmail(1696): <-dnotify_parent + 119 sendmail(1696): ->inotify_dentry_parent_queue_event + 127 sendmail(1696): <-inotify_dentry_parent_queue_event + 133 sendmail(1696): ->inotify_inode_queue_event + 141 sendmail(1696): <-inotify_inode_queue_event + 146 sendmail(1696): <-vfs_read + 151 sendmail(1696):<-sys_read +</screen> +</example> + + + </section> + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml new file mode 100644 index 00000000..51f57f6f --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml @@ -0,0 +1,73 @@ +<?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> + <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> +global reads, writes, total_io + +probe kernel.function("vfs_read").return { + reads[execname()] += $return +} + +probe kernel.function("vfs_write").return { + writes[execname()] += $return +} + +probe timer.s(1) { + foreach (p in reads) + total_io[p] += reads[p] + foreach (p in writes) + total_io[p] += writes[p] + foreach(p in total_io- limit 10) + printf("%15s r: %8d KiB w: %8d KiB\n", + p, reads[p]/1024, + writes[p]/1024) + printf("\n") + # Note we don't zero out reads, writes and total_io, + # so the values are cumulative since the script started. +} +</programlisting> +</para> +</formalpara> + +<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> + </section> + + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml new file mode 100644 index 00000000..68b337f1 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml @@ -0,0 +1,80 @@ +<?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="traceio2sect"> + <title>I/O Monitoring (By Device)</title> + + <remark> + example from http://sourceware.org/systemtap/examples/io/traceio2.stp, but error + </remark> + + <remark> + WAR STORY: http://sourceware.org/systemtap/wiki/WSDeviceMonitor?highlight=((WarStories)), but script errored + </remark> + + <remark> + was able to correct script through http://sourceware.org/systemtap/wiki/WSFileMonitor?highlight=((WarStories)) + </remark> + + <para> + This section describes how to monitor I/O activity on a specific device. + </para> + +<formalpara id="traceio2"> + <title>traceio2.stp</title> +<para> +<programlisting> +probe kernel.function ("vfs_write"), + kernel.function ("vfs_read") +{ + dev_nr = $file->f_dentry->d_inode->i_sb->s_dev + inode_nr = $file->f_dentry->d_inode->i_ino + if (dev_nr == ($1 << 20 | $2)) + printf ("%s(%d) %s 0x%x\n", execname(), pid(), probefunc(), dev_nr) +} +</programlisting> +</para> +</formalpara> + +<para condition="fedora">For some kernel versions (e.g. <filename>2.6.21-1.3194.fc7</filename>, you may need to revise <xref linkend="traceio2"/> accordingly. SystemTap will output the following error if you need to do so:</para> + +<screen condition="fedora"> +semantic error: field 'f_dentry' not found +</screen> + +<para condition="fedora">If this is the case, revise <xref linkend="traceio2"/> by deleting the following lines in the script:</para> + +<programlisting condition="fedora"> + dev_nr = $file->f_dentry->d_inode->i_sb->s_dev + inode_nr = $file->f_dentry->d_inode->i_ino +</programlisting> + +<para condition="fedora">Replace those lines with:</para> + +<programlisting condition="fedora"> + dev_nr = $file->f_path->dentry->d_inode->i_sb->s_dev + inode_nr = $file->f_path->dentry->d_inode->i_ino +</programlisting> + +<para><xref linkend="traceio2"/> takes 2 arguments: the <emphasis>major</emphasis> and <emphasis>minor</emphasis> numbers of the device you wish to monitor. Its output includes the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), and the device number (in hex format).</para> + +<remark>please verify if "0x800005" is "device number (in hex format)", and why it needs to be stated buy </remark> + +<para>The following example is an excerpt from the full output of <command>stap traceio2.stp 8 5</command>, where <computeroutput>8 5</computeroutput> is the MAJOR:MINOR device number of <filename>/dev/sda5</filename> (which we determined through <command>cat /sys/block/sda/sda5/dev</command>).</para> + +<example id="traceio2output"> + <title><xref linkend="traceio2"/> Sample Output</title> +<screen> +[...] +synergyc(3722) vfs_read 0x800005 +synergyc(3722) vfs_read 0x800005 +cupsd(2889) vfs_write 0x800005 +cupsd(2889) vfs_write 0x800005 +cupsd(2889) vfs_write 0x800005 +[...] +</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 03e515ff..d3d592ca 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml @@ -18,15 +18,21 @@ <remark>case studies and more info on some scripts here - http://sourceware.org/systemtap/wiki/WarStories</remark> - <xi:include href="Useful_Scripts-Disk.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Useful_Scripts-Disk.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="Useful_Scripts-disktop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Useful_Scripts-IO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Useful_Scripts-IO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="Useful_Scripts-iotop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Useful_Scripts-Kernel.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-traceio.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Useful_Scripts-traceio2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Useful_Scripts-Kernel.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-inodewatch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Useful_Scripts-inodewatch2.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" /> - <xi:include href="Useful_Scripts-Others.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Useful_Scripts-Others.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> <!-- <xi:include href="" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index ebf71276..0e5b662d 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -70,6 +70,19 @@ </listitem> </varlistentry> +<varlistentry> + <term>-x <replaceable>process ID</replaceable></term> + <listitem> + <para>Sets the SystemTap handler function <command>target()</command> to the specified process ID. For more information about <command>target()</command>, refer to <xref linkend="systemtapscript-handlers"/>.</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>-c <replaceable>command</replaceable></term> + <listitem> + <para>Sets the SystemTap handler function <command>target()</command> to the specified command. Note that you must use the full path to the specified command; for example, instead of specifying <command>cp</command>, use <command>/bin/cp</command> (as in <command>stap <replaceable>script</replaceable> -c /bin/cp</command>). For more information about <command>target()</command>, refer to <xref linkend="systemtapscript-handlers"/>.</para> + </listitem> +</varlistentry> <!-- <varlistentry> <term></term> |