From 3cb837a1af0ccad4ba335ee6b21e906a3021d198 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Mon, 20 Oct 2008 16:29:56 +1000 Subject: [PATCH] revised as per latest from wcohen, started out errors, minor edits throughout --- .../en-US/Errors.xml | 112 ++++++++++++++++++ .../en-US/Installation.xml | 20 ++-- .../en-US/Introduction.xml | 4 +- .../en-US/Scripts.xml | 36 +++--- .../Understanding_How_SystemTap_Works.xml | 4 +- .../en-US/Useful_Scripts-disktop.xml | 13 -- .../en-US/Useful_Scripts-sockettrace.xml | 71 +++++++++++ .../en-US/Useful_Scripts-threadtimes.xml | 106 +++++++++++++++++ .../en-US/Useful_SystemTap_Scripts.xml | 2 + .../en-US/Using_SystemTap.xml | 2 +- 10 files changed, 326 insertions(+), 44 deletions(-) create mode 100644 doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml create mode 100644 doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml diff --git a/doc/SystemTap_Beginners_Guide/en-US/Errors.xml b/doc/SystemTap_Beginners_Guide/en-US/Errors.xml index 21351e084..e0a61aaee 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Errors.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Errors.xml @@ -7,5 +7,117 @@ By type - http://sourceware.org/systemtap/tutorial/node23.html + This chapter explains the most common errors you may encounter while using SystemTap. + +
+ Parse and Type Errors + +These types of errors occur before the translation phase of a SystemTap session, i.e. before the script is translated into C. + +parse error: expected <replaceable>foo</replaceable>, saw <replaceable>bar</replaceable> + +The script contains a grammatical/typographical error. SystemTap detected type of construct that is incorrect, given the context of the probe. + + + +need more clarification (example) on this; could not replicate. how to replicate? + +parse error: embedded code in unprivileged script + + The script contains unsafe constructs; in most cases, embedded C. SystemTap allows you to embed C code in a script, which is useful if there are no tapsets to suit your purposes. However, some embedded C constructs may not be safe; as such, SystemTap warns you with this error if such constructs appear in the script. (from ) is an example of a script that contains embedded C. + +If you are sure of the safety of any similar constructs in the script, run the script in "guru" mode by using the option -g (i.e. stap -g script). + + + semantic error: type mismatch for identifier '<replaceable>foo</replaceable>' ... string vs. long + + + The function foo in the script used the wrong type of variable (i.e. %s or %d). This error will present itself in , since the function execname should be referenced using %s, not %d. + + + + + error-variable.stp + +probe syscall.open +{ + printf ("%d(%d) open\n", execname(), pid()) +} + + + + + semantic error: unresolved type for identifier '<replaceable>foo</replaceable>' +TBD + + + + semantic error: Expecting symbol or array index expression +TBD + + +
+ +
+ Symbol-Related Errors + +TBD + + + while searching for arity <replaceable>N</replaceable> function, semantic error: unresolved function call +TBD + + + + semantic error: array locals not supported: + TBD + + + + semantic error: variable ’<replaceable>foo</replaceable>’ modified during ’<replaceable>construct</replaceable>’ + TBD + +
+ +
+ Probe Errors + +TBD + + + semantic error: probe point mismatch at position <replaceable>N</replaceable>, while resolving probe point <replaceable>foo</replaceable> + SystemTap did not understand what the event / handler function foo refers to. This usually means that SystemTap could not find a match for foo in the tapset library. + + +how to explain N in previous? "The divergence from the “tree” of probe point namespace is at position N (starting with zero at left)." + + + semantic error: no match for probe point, while resolving probe point <replaceable>foo</replaceable> + The events / handler function foo could not be resolved altogether, for a variety of reasons. This error occurs when the script contains the event kernel.function("blah"), and blah does not exist. In some cases, the error could also mean the script contains an invalid kernel file name or source line number. + + + + semantic error: unresolved target-symbol expression + TBD + + + + semantic error: libdwfl failure + TBD + + + + semantic error: cannot find foo debuginfo + TBD + + + +
+ diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml index 8670db596..f9c9a8195 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml @@ -83,7 +83,7 @@ gpgcheck=0 - In , repository is the full URL of the repository containing the packages you wish to install. The name= parameter, along with the title ([packages]) and filename, can be set arbitrarily, as long as you use the .repo filename extension. + In , repository is the full URL of the repository containing the packages you wish to install. The name= parameter, along with the title ([packages]) and filename, can be set arbitrarily. Remember to always use the .repo filename extension. @@ -118,7 +118,7 @@ As mentioned earlier in , kernel-debuginf Important - The version of the -devel, -debuginfo and -debuginfo-common packages must match the kernel you wish to probe with SystemTap exactly. + The version and architecture of the -devel, -debuginfo and -debuginfo-common packages must match the kernel you wish to probe with SystemTap exactly. You can download the necessary packages via your web browser. Once you have downloaded the packages, install them by running rpm -ivh package names. @@ -142,24 +142,24 @@ As mentioned earlier in , kernel-debuginf simple.stp -probe timer.s(2) {exit()} +probe kernel.function("vfs_read") {exit()} - is a SystemTap script that simply closes after 2 seconds. To run the test, use stap -v simple.stp. If the SystemTap deployment was successful, you should get the following verbose output: + is a SystemTap script that simply exits the first time it detects a virtual file system read. If the SystemTap deployment was successful, you should get the following verbose output: -Pass 1: parsed user script and 55 library script(s) in 340usr/0sys/356real ms. -Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 10usr/10sys/7real ms. -Pass 3: translated to C into "/tmp/stapwPJf4N/stap_166903963eb5e3849b44f0ba89d442a8_252.c" in 0usr/0sys/1real ms. -Pass 4: compiled C into "stap_166903963eb5e3849b44f0ba89d442a8_252.ko" in 2050usr/230sys/2274real ms. +Pass 1: parsed user script and 55 library script(s) in 340usr/10sys/380real ms. +Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 280usr/290sys/745real ms. +Pass 3: translated to C into "/tmp/stapS1CuuS/stap_dd516743892b10a24cd36ef327265169_323.c" in 0usr/0sys/0real ms. +Pass 4: compiled C into "stap_dd516743892b10a24cd36ef327265169_323.ko" in 2050usr/220sys/2541real ms. Pass 5: starting run. -Pass 5: run completed in 30usr/220sys/2260real ms. +Pass 5: run completed in 40usr/210sys/260real ms. - The last two lines of the output (i.e. beginning with Pass 5 indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, and close it with no errors. + The last two lines of the output (i.e. beginning with Pass 5 indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in the case of , a virtual file system read), and close it with no errors. Several handlers and functions in and are defined in tapsets. For example, thread_indent() is defined in indent.stp. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml index 69877c5b0..cfc76c07e 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml @@ -19,19 +19,6 @@ disktop.stp -#!/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 diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml new file mode 100644 index 000000000..431735164 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml @@ -0,0 +1,71 @@ + + + + +
+ Tracing Functions Called in Network Socket Code + + + + http://sourceware.org/systemtap/examples/network/socket-trace.stp + + + +This section describes how to trace functions called from the kernel's net/socket.c file. This task helps you identify, in finer detail, how each process interacts with the network at the kernel level. + + + sockettrace.stp + + +probe kernel.function("*@net/socket.c").call { + printf ("%s -> %s\n", thread_indent(1), probefunc()) +} +probe kernel.function("*@net/socket.c").return { + printf ("%s <- %s\n", thread_indent(-1), probefunc()) +} + + + + + is identical to , which was earlier used in to illustrate how thread_indent() works. + + + <xref linkend="sockettrace"/> Sample Output + +[...] +0 Xorg(3611): -> sock_poll +3 Xorg(3611): <- sock_poll +0 Xorg(3611): -> sock_poll +3 Xorg(3611): <- sock_poll +0 gnome-terminal(11106): -> sock_poll +5 gnome-terminal(11106): <- sock_poll +0 scim-bridge(3883): -> sock_poll +3 scim-bridge(3883): <- sock_poll +0 scim-bridge(3883): -> sys_socketcall +4 scim-bridge(3883): -> sys_recv +8 scim-bridge(3883): -> sys_recvfrom +12 scim-bridge(3883):-> sock_from_file +16 scim-bridge(3883):<- sock_from_file +20 scim-bridge(3883):-> sock_recvmsg +24 scim-bridge(3883):<- sock_recvmsg +28 scim-bridge(3883): <- sys_recvfrom +31 scim-bridge(3883): <- sys_recv +35 scim-bridge(3883): <- sys_socketcall +[...] + + + + contains a 3-second excerpt of the output for . Each line contains the following information, on the order that they appear: + + + The time delta (in microseconds) since the previous entry; i.e. the number of microseconds since the last traced function call. + + The process name (and its corresponding ID) that made the function call. + + An arrow signifying whether the call was an entry (<-) or an exit (->); the indentations help you match specific function call entries with their corresponding exits. + + The name of the function called by the process. + +
+ diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml new file mode 100644 index 000000000..ccf8f8d06 --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml @@ -0,0 +1,106 @@ + + + + +
+ Determining Time Spent in Kernel and User Space + + + + http://sourceware.org/systemtap/examples/profiling/thread-times.stp + + + +This section illustrates how to determine the amount of time any given thread is spending in either kernel or user-space. + + + threadtimes.stp + + +function pc:long () %{ /* pure */ + if (CONTEXT->regs) + THIS->__retvalue = (uint64_t) REG_IP (CONTEXT->regs); +%} + +function kta:long (pc:long) %{ /* pure */ /* is given PC a kernel text address? */ +#if defined (__ia64__) + THIS->__retvalue = ((unsigned long)REG_IP(CONTEXT->regs) >= (unsigned long)KERNEL_START); +#else + THIS->__retvalue = ((unsigned long)REG_IP(CONTEXT->regs) >= (unsigned long)PAGE_OFFSET); +#endif +%} + +probe timer.profile { + tid=tid() + kernel_p = kta(pc()) + if (kernel_p) + kticks[tid] <<< 1 + else + uticks[tid] <<< 1 + ticks <<< 1 +} + +global uticks, kticks, ticks + +global tids + +probe timer.s(10), end { + # gather all seen tids into a single array + foreach (tid in kticks) tids[tid] += @count(kticks[tid]) + foreach (tid in uticks) tids[tid] += @count(uticks[tid]) + + allticks = @count(ticks) + printf ("%5s %7s %7s (of %d ticks)\n", "tid", "%user", "%kernel", allticks) + foreach (tid in tids- limit 20) { + uscaled = @count(uticks[tid])*10000/allticks + kscaled = @count(kticks[tid])*10000/allticks + printf ("%5d %3d.%02d%% %3d.%02d%%\n", + tid, uscaled/100, uscaled%100, kscaled/100, kscaled%100) + } + printf("\n") + + delete uticks + delete kticks + delete ticks + delete tids +} + + + + + lists the top 20 processes currently taking up CPU time within a 5-second sample, along with the total number of CPU ticks made during the sample. The output of this script also notes the percentage of CPU time each process used, as well as whether that time was spent in kernel space or user space. + +To run , you need to use the -g option (i.e. stap -g threadtimes.stp). This is because the script contains embedded C. + + contains a 5-second sample of the output for : + + + <xref linkend="threadtimes"/> Sample Output + + tid %user %kernel (of 20002 ticks) + 0 0.00% 87.88% +32169 5.24% 0.03% + 9815 3.33% 0.36% + 9859 0.95% 0.00% + 3611 0.56% 0.12% + 9861 0.62% 0.01% +11106 0.37% 0.02% +32167 0.08% 0.08% + 3897 0.01% 0.08% + 3800 0.03% 0.00% + 2886 0.02% 0.00% + 3243 0.00% 0.01% + 3862 0.01% 0.00% + 3782 0.00% 0.00% +21767 0.00% 0.00% + 2522 0.00% 0.00% + 3883 0.00% 0.00% + 3775 0.00% 0.00% + 3943 0.00% 0.00% + 3873 0.00% 0.00% + + + +
+ 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 ecfc2341c..49c10b9f6 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml @@ -32,6 +32,8 @@ + +