diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide')
6 files changed, 221 insertions, 11 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index b928372b..8888c7b8 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 (i.e. <command>stap allsyscalls.stp -x <replaceable>process ID</replaceable>).</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,83 @@ 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 loosely based on C and <command>awk</command> syntax; this section describes several of the most commonly used ones.</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.</para> + + +<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> + + + + </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-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-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_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml index 03e515ff..d8ec61f2 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml @@ -22,6 +22,7 @@ <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-iotop.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-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-Signals.xml" 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> |