diff options
Diffstat (limited to 'doc/SystemTap_Beginners_Guide/en-US')
11 files changed, 192 insertions, 83 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml index ebac139f..32fdf021 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml @@ -40,9 +40,9 @@ delta = gettimeofday_s() - foo[execname()] </screen> </example> -<para>In <xref linkend="arrayreadingvaluesfrom"/>, the first statement sets a timestamp associated with the returned value of the handler function <command>execname()</command> as a <emphasis>reference point</emphasis>. The second statement computes a value for the variable <command>delta</command> by subtracting the associated value the reference point from the current <command>gettimeofday_s()</command>.</para> +<para>In <xref linkend="arrayreadingvaluesfrom"/>, the first statement sets a timestamp associated with the returned value of the handler function <command>execname()</command> as a <emphasis>reference point</emphasis>. The second statement computes a value for the variable <command>delta</command> by subtracting the associated value the reference point from the current <command>gettimeofday_s()</command>. Note that the first statement writes the value of <command>gettimeofday_s()</command> into the appropriate key of array <literal>foo</literal>, while in the second statement the value of <command>foo[execname()]</command> is <emphasis>read</emphasis> from the array in order to compute for <literal>delta</literal>.</para> -<para>In this situation, if the <command><replaceable>index_expression</replaceable></command> cannot find the unique key, it returns a null value (zero) by default. </para> +<para>In this situation, if the <command><replaceable>index_expression</replaceable></command> cannot find the unique key, it returns a value of 0 (for numerical operations, such as <xref linkend="arrayreadingvaluesfrom"/>) or a null/empty string value (for string operations) by default. </para> </section> <section id="arrayops-increment"> <title>Incrementing Associated Values</title> @@ -117,18 +117,19 @@ probe timer.s(3) <example id="simplevfsreadprintnotcumulative"> <title>vfsreads-per-2secs.stp</title> <programlisting> -global reads
-probe kernel.function("vfs_read")
-{
- reads[execname()] ++
-}
-probe timer.s(2)
-{
- printf("=======\n")
- foreach (count in reads+)
- printf("%s : %d \n", count, reads[count])
- delete reads
-}
+global reads +probe kernel.function("vfs_read") +{ + reads[execname()] ++ + +} +probe timer.s(2) +{ + printf("=======\n") + foreach (count in reads+) + printf("%s : %d \n", count, reads[count]) + delete reads +} </programlisting> </example> @@ -139,28 +140,28 @@ probe timer.s(2) <para>You can have multiple array operations within the same probe. Using the examples from <xref linkend="arrayops-foreach"/> and <xref linkend="arrayops-deleting"/> , you can track the number of VFS reads each process makes per 2-second period <emphasis>and</emphasis> tally the cumulative VFS reads of those same processes. Consider the following example:</para> <screen> -global reads, totalreads
-
-probe kernel.function("vfs_read")
-{
- reads[execname()] ++
- totalreads[execname()] ++
-}
-
-probe timer.s(2)
-{
- printf("=======\n")
- foreach (count in reads+)
- printf("%s : %d \n", count, reads[count])
- delete reads
-
-}
-probe end
-{
- printf("TOTALS\n")
- foreach (total in totalreads+)
- printf("%s : %d \n", total, totalreads[total])
-}
+global reads, totalreads + +probe kernel.function("vfs_read") +{ + reads[execname()] ++ + totalreads[execname()] ++ +} + +probe timer.s(2) +{ + printf("=======\n") + foreach (count in reads+) + printf("%s : %d \n", count, reads[count]) + delete reads + +} +probe end +{ + printf("TOTALS\n") + foreach (total in totalreads+) + printf("%s : %d \n", total, totalreads[total]) +} </screen> <para>In this example, the arrays <command>reads</command> and <command>totalreads</command> track the same information, and are printed out in a similar fashion. The only difference here is that <command>reads</command> is cleared every 2-second period, whereas <command>totalreads</command> keeps growing.</para> @@ -174,18 +175,19 @@ probe end <example id="simplevfsreadprintif"> <title>vfsreads-stop-on-stapio.stp</title> <programlisting> -global reads
-probe kernel.function("vfs_read")
-{
- reads[execname()] ++
-}
-probe timer.s(2)
-{
- printf("=======\n")
- foreach (count in reads+)
- printf("%s : %d \n", count, reads[count])
- if(reads["stapio"] >= 20)
- {exit()}
+global reads +probe kernel.function("vfs_read") +{ + reads[execname()] ++ +} + +probe timer.s(2) +{ + printf("=======\n") + foreach (count in reads+) + printf("%s : %d \n", count, reads[count]) + if(reads["stapio"] >= 20) + {exit()} } </programlisting> </example> @@ -206,27 +208,118 @@ if([<replaceable>index_expression</replaceable>] in <replaceable>array_name</rep <example id="simplesimplevfsreadprintifmember"> <title>vfsreads-stop-on-stapio2.stp</title> <programlisting> -global reads
-
-probe kernel.function("vfs_read")
-{
- reads[execname()] ++
-}
-
-probe timer.s(2)
-{
- printf("=======\n")
- foreach (count in reads+)
- printf("%s : %d \n", count, reads[count])
- if(["stapio"] in reads)
- {printf("stapio read detected, exiting\n")
- exit()
- }
-}
+global reads + +probe kernel.function("vfs_read") +{ + reads[execname()] ++ +} + +probe timer.s(2) +{ + printf("=======\n") + foreach (count in reads+) + printf("%s : %d \n", count, reads[count]) + if(["stapio"] in reads) + {printf("stapio read detected, exiting\n") + exit() + } +} </programlisting> </example> <para>The <command>if(["stapio"] in reads)</command> statement instructs the script to print <computeroutput>stapio read detected, exiting</computeroutput> once the unique key <command>stapio</command> is added to the array <command>reads</command>.</para> </section> +<section id="arrayops-aggregates"> + <title>Computing for Statistical Aggregates</title> + +<para>Statistical aggregates are used to collect statistics on numerical values where it is important to accumulate new data quickly and in large volume (i.e. storing only aggregated stream statistics). Statistical aggregates can be used in global variables or as elements in an array.</para> + +<para>To add value to a statistical aggregate, use the operator <command><<< <replaceable>value</replaceable></command>.</para> + +<remark>need more examples of supported rvalues, e.g. length, count, and what each one does.</remark> + +<example id="simpleaggregates"> + <title>stat-aggregates.stp</title> +<programlisting> +global writes +probe vfs_write +{ +writes[execname()] <<< count +} +</programlisting> +</example> + +<para>In <xref linkend="simpleaggregates"/>, the operator <command><<< count</command> <emphasis>stores</emphasis> the amount returned by <literal>count</literal> to to the associated value of the corresponding <command>execname()</command> in the <literal>writes</literal> array. Remember, these values are <emphasis>stored</emphasis>; they are not added to the associated values of each unique key, nor are they used to replace the current associated values. In a manner of speaking, think of it as having each unique key (<command>execname()</command>) having multiple associated values, accumulating with each probe handler run.</para> + +<note> + <title>Note</title> + <para>In the context of <xref linkend="simpleaggregates"/>, <literal>count</literal> returns the amount of data written by the returned <command>execname()</command> to the virtual file system.</para> +</note> + +<para>To extract data collected by statistical aggregates, use the syntax format <command>@<replaceable>extractor</replaceable>(<replaceable>variable/array index expression</replaceable>)</command>. <command><replaceable>extractor</replaceable></command> can be any of the following integer extractors:</para> + +<variablelist> + +<varlistentry> + <term>count</term> +<listitem> +<para> + Returns the number of all values stored into the variable/array index expression. Given the sample probe in <xref linkend="simpleaggregates"/>, the expression <command>@count(writes[execname()])</command> will return <emphasis>how many values are stored</emphasis> in each unique key in array <literal>writes</literal>. +</para> +</listitem> +</varlistentry> + +<varlistentry> + <term>sum</term> +<listitem> +<para> + Returns the sum of all values stored into the variable/array index expression. Again, given sample probe in <xref linkend="simpleaggregates"/>, the expression <command>@sum(writes[execname()])</command> will return <emphasis>the total of all values stored</emphasis> in each unique key in array <literal>writes</literal>. +</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>min</term> +<listitem> +<para> + Returns the smallest among all the values stored in the variable/array index expression. +</para> +</listitem> +</varlistentry> + +<varlistentry> + <term>max</term> +<listitem> +<para> + Returns the largest among all the values stored in the variable/array index expression. +</para> +</listitem> +</varlistentry> + +<varlistentry> + <term>avg</term> +<listitem> +<para> + Returns the average of all values stored in the variable/array index expression. +</para> +</listitem> +</varlistentry> + + + +<!-- +<varlistentry> + <term></term> +<listitem> +<para> +</para> +</listitem> +</varlistentry> +--> + +</variablelist> +</section> + </section>
\ No newline at end of file diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml index 6fc99f1d..cf8b2fea 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml @@ -27,7 +27,7 @@ foo["harry"] = 25 <important> <title>Important</title> - <para>Arrays are normally used in multiple probes throughout a script: in most cases, one probe builds the arrays while another probe processes the information collected by the array (e.g. print its elements). Since the treatment of arrays is similar to that of variables, arrays must also be declared globally with the statement <command>global</command> when they are used by multiple probes.</para> + <para>All associate arrays must be declared as <command>global</command>, regardless of whether the associate array is used in one or multiple probes. </para> </important> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Errors.xml b/doc/SystemTap_Beginners_Guide/en-US/Errors.xml index 83022a31..55081185 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Errors.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Errors.xml @@ -12,7 +12,7 @@ <section id="parsetype"> <title>Parse and Type Errors</title> -<para>These types of errors occur while SystemTap attempts to parse and translate the script into C, prior to being converted into a kernel module.</para> +<para>These types of errors occur while SystemTap attempts to parse and translate the script into C, prior to being converted into a kernel module. Specifically, type errors result from operations that assign invalid values to variables or arrays.</para> <formalpara><title>parse error: expected <replaceable>foo</replaceable>, saw <replaceable>bar</replaceable></title> @@ -59,9 +59,9 @@ probe syscall.open </section> <section id="symbolerrors"> - <title>Symbol-Related Errors</title> + <title>Symbol Errors</title> -<para>TBD</para> +<para>Symbol errors result from operations in the script that process variables, arrays, or function calls incorrectly. Unlike "type" errors — which assign invalid values to a variable or array — symbol errors prevent the script from assigning any value altogether.</para> <formalpara> <title>while searching for arity <replaceable>N</replaceable> function, semantic error: unresolved function call</title> @@ -82,14 +82,14 @@ probe syscall.open <section id="probingerrors"> <title>Probe Errors</title> -<para>TBD</para> +<para>Probe errors result from the use of invalid events (e.g. events that could not be found in the tapset library), or the use of handlers that are invalid in the context of the probe. </para> <formalpara> <title>semantic error: probe point mismatch at position <replaceable>N</replaceable>, while resolving probe point <replaceable>foo</replaceable></title> <para>SystemTap did not understand what the event / handler function <computeroutput><replaceable>foo</replaceable></computeroutput> refers to. This usually means that SystemTap could not find a match for <computeroutput><replaceable>foo</replaceable></computeroutput> in the tapset library.</para> </formalpara> -<remark>how to explain N in previous? "The divergence from the “tree” of probe point namespace is at position N (starting with zero at left)." </remark> +<remark>how to explain N in previous? "The divergence from the “tree” of probe point namespace is at position N (starting with zero at left)." (from tutorial) </remark> <formalpara> <title>semantic error: no match for probe point, while resolving probe point <replaceable>foo</replaceable></title> @@ -98,17 +98,17 @@ probe syscall.open <formalpara> <title>semantic error: unresolved target-symbol expression</title> - <para>TBD</para> + <para>A handler in the script references a target variable, but the value of the variable could not be resolved. This error could also mean that a handler is referencing a target variable that is not valid at all in the context when it was referenced. </para> </formalpara> <formalpara> <title>semantic error: libdwfl failure </title> - <para>TBD</para> + <para>There was a problem processing the debugging information. In most cases, this error results from the installation of a <filename>kernel-debuginfo</filename> RPM whose version does not match the probed kernel perfectly. Sometimes, the installed <filename>kernel-debuginfo</filename> RPM itself may have some consistency / correctness problems.</para> </formalpara> <formalpara> - <title>semantic error: cannot find foo debuginfo</title> - <para>TBD</para> + <title>semantic error: cannot find <replaceable>foo</replaceable> debuginfo</title> + <para>SystemTap could not find a suitable <filename>kernel-debuginfo</filename> at all. </para> </formalpara> <!-- <formalpara> 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 d92fdfa8..041a4689 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml @@ -19,7 +19,7 @@ <title>disktop.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/io/disktop.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/io/disktop.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml index 0f0b9a7a..bcab2c47 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-functioncalls.xml @@ -22,7 +22,7 @@ no script in examples <title>functioncallcount.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/profiling/functioncallcount.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/profiling/functioncallcount.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml index 2a1fa018..34e51076 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-futexes.xml @@ -26,7 +26,7 @@ no script in examples <title>futexes.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/process/futexes.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/process/futexes.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> 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 b908313e..4fd41c6e 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml @@ -11,7 +11,7 @@ <title>iotop.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/io/iotop.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/io/iotop.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml index 6c66eeaf..7e01a1f8 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml @@ -22,11 +22,27 @@ <title>nettop.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/network/nettop.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/network/nettop.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> +<para>Note that <command>function print_activity()</command> uses the following constructs:</para> + +<screen> +n_xmit ? @sum(ifxmit[pid, dev, exec, uid])/1024 : 0, +n_recv ? @sum(ifrecv[pid, dev, exec, uid])/1024 : 0 +</screen> + +<para>These constructs are if/else conditionals. The first statement is simply a more concise way of writing:</para> + +<screen> +if n_recv != 0 then + @sum(ifrecv[pid, dev, exec, uid])/1024 +else + 0 +</screen> + <para><xref linkend="nettop"/> tracks which processes are generating network traffic on the system, and provides the following information about each process:</para> <itemizedlist> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml index 6d84056b..abd2d9d1 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-sockettrace.xml @@ -18,7 +18,7 @@ <title>socket-trace.stp</title> <para> <programlisting> - <xi:include parse="text" href="extras/extras/network/socket-trace.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include parse="text" href="extras/testsuite/systemtap.examples/network/socket-trace.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml index a5d643c6..8df14aca 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-threadtimes.xml @@ -18,7 +18,7 @@ <title>thread-times.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/profiling/thread-times.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/profiling/thread-times.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml index 7ed3cdca..71bd1984 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml @@ -12,7 +12,7 @@ <title>traceio.stp</title> <para> <programlisting> -<xi:include parse="text" href="extras/extras/io/traceio.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<xi:include parse="text" href="extras/testsuite/systemtap.examples/io/traceio.stp" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> </para> </formalpara> |