diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide/en-US')
3 files changed, 122 insertions, 12 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml index 6f1b2a0a..b19f5e48 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml @@ -5,7 +5,7 @@ <chapter id="introduction"> <title>Introduction</title> <para> - SystemTap is a tracing and probing tool that provides users deep technical insight into what the operating system (particularly, the kernel) is doing at any given time. It provides information similar to the output of tools like <command>netstat</command>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide information that is more "granular" in nature. + SystemTap is a tracing and probing tool that provides users to study and monitor the activities of the operating system (particularly, the kernel) in fine detail. It provides information similar to the output of tools like <command>netstat</command>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide information that is more "granular" in nature. </para> <para> @@ -23,7 +23,7 @@ <para>Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running its suite of tools against specific <firstterm>tapsets</firstterm> or SystemTap scripts.</para> - <para>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. This could present a steep learning curve for administrators or developers whose knowledge of the Linux kernel is little to none.</para> + <para>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As such, much of the existing documentation for SystemTap is primarily for advanced users. This could present a steep learning curve for administrators or developers whose knowledge of the Linux kernel is little to none.</para> <para>In line with that, the main goals of the <citetitle>SystemTap Beginner's Guide</citetitle> are as follows:</para> 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> 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 de5d41b0..76296507 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 @@ -34,7 +34,7 @@ <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>SystemTap then loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step> + <step><para>SystemTap loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step> <step><para>As the events occur, their corresponding handlers are executed.</para></step> |