diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide/en-US/Scripts.xml')
| -rw-r--r-- | doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 128 |
1 files changed, 119 insertions, 9 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index d61ec1cf..bbd265c2 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -13,9 +13,12 @@ As stated in <xref linkend="understanding-how-systemtap-works"/>, SystemTap scripts are made up of two components: <emphasis>events</emphasis> and <emphasis>handlers</emphasis>. Once a SystemTap session is underway, SystemTap monitors the operating system for the specified events and executes the handlers as they occur. </para> + <note> <title>Note</title> <para>An event and its corresponding handler is collectively called a <emphasis>probe</emphasis>. A SystemTap script can have multiple probes.</para> + + <para>A probe's handler is also commonly referred to as a <emphasis>probe body</emphasis>.</para> </note> <para> @@ -92,11 +95,57 @@ probe kernel.function("*@net/socket.c").return { } <varlistentry> <term>syscall.<replaceable>[system_call]</replaceable></term> <listitem> - <para>The entry to the system call <replaceable>[system_call]</replaceable>. Similar to <command>kerne.function</command>, appending a <command>return</command> to the statement specifies the exit of the system call. For example, to specify the entry of the system call <command>close</command>, use <command>syscall.close.return</command>.</para> + <para>The entry to the system call <replaceable>[system_call]</replaceable>. Similar to <command>kernel.function</command>, appending a <command>return</command> to the statement specifies the exit of the system call. For example, to specify the entry of the system call <command>close</command>, use <command>syscall.close.return</command>.</para> <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>timer.ms()</term> + <listitem> + <para>An event that specifies a handler to be executed "after X number of milliseconds". For example:</para> + +<example id="timer"><title>Using timer.ms</title> +<programlisting> +probe timer.ms(4000) +{ + exit() +} +</programlisting> +</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). +</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>--> <!-- <varlistentry> <term></term> @@ -114,10 +163,12 @@ probe kernel.function("*@net/socket.c").return { } SystemTap supports the use of a large collection of probe events. For more information about supported events, refer to <command>man stapprobes</command>. The <citetitle>SEE ALSO</citetitle> section of <command>man stapprobes</command> also contains links to other <command>man</command> pages that discuss supported events for specific subsystems and components. </para> </important> + +<remark>is reference appropriate? too advanced for readers (it seems so to me)? please advise.</remark> </section> <section id="systemtapscript-handlers"> - <title>Handlers</title> + <title>Handlers/Probe Body</title> <para> Consider the following sample script: @@ -142,7 +193,10 @@ probe begin <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: </para> + </formalpara> +<remark>is "handler tool" appropriate?</remark> + <programlisting> printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]</replaceable>) @@ -164,10 +218,11 @@ printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]< <title>Using Variables In printf ( ) Statements</title> <programlisting> # This probe will need to be manually terminated with Ctrl-C -probe syscall.open
-{
- printf ("%s(%d) open\n", execname(), pid())
-}
+probe syscall.open +{ + printf ("%s(%d) open\n", execname(), pid()) +} + </programlisting> </example> @@ -175,6 +230,8 @@ probe syscall.open <xref linkend="syscall-open"/> instructs SystemTap to probe all entries to the system call <command>open</command>; for each event, it prints the current <command>execname()</command> (which is a string) and <command>pid()</command> (which is a number), followed by the word <command>open</command>. A snippet of this probe's output would look like: </para> +<remark>editorial review: does a clarification that "variable1" is to "argument1", "variable2" is to "argument2", or is this clear enough?</remark> + <screen> vmware-guestd(2206) open hald(2360) open @@ -187,11 +244,13 @@ hald(2360) open </screen> <formalpara> - <title>Handler Functions</title> + <title>Handler Functions</title> <para>SystemTap supports a wide variety of handler functions that can be used as <command>printf ()</command> arguments. <xref linkend="syscall-open"/> uses the handler functions <command>execname()</command> (current process name) and <command>pid()</command> (current process ID).</para> </formalpara> - <para>The following is a list of commonly-used handler functions:</para> - + +<remark>is "handler function" an appropriate term?</remark> + + <para>The following is a list of commonly-used handler functions:</para> <variablelist> <varlistentry> @@ -242,6 +301,56 @@ hald(2360) open <para>If known, the name of the function in which the probe was placed.</para> </listitem> </varlistentry> + +<varlistentry> + <term>thread_indent()</term> + <listitem> + <para>This particular handler function is quite useful, providing you with a way to better organize your print results. When used with an indentation parameter (for example, <command>-1</command>), it allows the probe to internally store an "indentation counter" for each thread (identified by ID, as in <command>tid</command>). It then returns a string with some generic trace data along with an appropriate number of indentation spaces.</para> + + <para>The generic data included in the returned string includes a timestamp (number of microseconds since the most recent initial indentation), a process name, and the thread ID. This allows you to identify what functions were called, who called them, and the duration of each function call. + </para> + + <para> + Consider the following example on the use of <command>thread_indent()</command>: + </para> + +<example id="thread_indent"><title>Using thread_indent()</title> +<programlisting> +probe kernel.function("*@net/socket.c") +{ + printf ("%s -> %s\n", thread_indent(1), probefunc()) +} +probe kernel.function("*@net/socket.c").return +{ + printf ("%s <- %s\n", thread_indent(-1), probefunc()) +} +</programlisting> +</example> + <para><xref linkend="thread_indent"/> prints out the <command>thread_indent()</command> and probe functions at each event in the following format:</para> + +<screen> + 0 ftp(7223): -> sys_socketcall + 1159 ftp(7223): -> sys_socket + 2173 ftp(7223): -> __sock_create + 2286 ftp(7223): -> sock_alloc_inode + 2737 ftp(7223): <- sock_alloc_inode + 3349 ftp(7223): -> sock_alloc + 3389 ftp(7223): <- sock_alloc + 3417 ftp(7223): <- __sock_create + 4117 ftp(7223): -> sock_create + 4160 ftp(7223): <- sock_create + 4301 ftp(7223): -> sock_map_fd + 4644 ftp(7223): -> sock_map_file + 4699 ftp(7223): <- sock_map_file + 4715 ftp(7223): <- sock_map_fd + 4732 ftp(7223): <- sys_socket + 4775 ftp(7223): <- sys_socketcall +</screen> + +<remark>remember to add a reference later to "tapsets" from here, to clarify that thread_indent is defined in tapsets as a special function of sorts</remark> + + </listitem> +</varlistentry> <!-- <varlistentry> <term></term> @@ -254,6 +363,7 @@ hald(2360) open <para>For more information about supported handler functions, refer to <command>man stapfuncs</command>.</para> +<remark>will need a complete listing of supported handler functions? also, handler function descriptions seem ambiguous, please advise.</remark> <!-- <para> |