<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.5.7. Computing for Statistical Aggregates</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css" /><meta name="generator" content="publican 1.6" /><meta name="package" content="Systemtap-SystemTap_Beginners_Guide-1.0-en-US-2.0-2" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="arrayoperators.html" title="3.5. Array Operations in SystemTap" /><link rel="prev" href="arrayops-conditionals.html" title="3.5.6. Using Arrays in Conditional Statements" /><link rel="next" href="understanding-tapsets.html" title="3.6. Tapsets" /></head><body class=""><p id="title"><a class="left" href="http://www.fedoraproject.org"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="http://docs.fedoraproject.org"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="arrayops-conditionals.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="understanding-tapsets.html"><strong>Next</strong></a></li></ul><div class="section" title="3.5.7. Computing for Statistical Aggregates"><div class="titlepage"><div><div><h3 class="title" id="arrayops-aggregates">3.5.7. Computing for Statistical Aggregates</h3></div></div></div><a id="id2925331" class="indexterm"></a><a id="id2815497" class="indexterm"></a><a id="id2938920" class="indexterm"></a><a id="id2905631" class="indexterm"></a><a id="id2860583" class="indexterm"></a><div class="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.
</div><a id="id3110855" class="indexterm"></a><a id="id2854901" class="indexterm"></a><a id="id2969174" class="indexterm"></a><a id="id2939438" class="indexterm"></a><div class="para">
To add value to a statistical aggregate, use the operator <code class="command"><<< <em class="replaceable"><code>value</code></em></code>.
</div><div class="example" id="simpleaggregates"><div class="example-contents"><pre class="programlisting">
global reads
probe vfs.read
{
reads[execname()] <<< count
}
</pre></div><h6>Example 3.19. stat-aggregates.stp</h6></div><br class="example-break" /><a id="id2810312" class="indexterm"></a><a id="id2983300" class="indexterm"></a><a id="id3424270" class="indexterm"></a><a id="id2746250" class="indexterm"></a><div class="para">
In <a class="xref" href="arrayops-aggregates.html#simpleaggregates" title="Example 3.19. stat-aggregates.stp">Example 3.19, “stat-aggregates.stp”</a>, the operator <code class="command"><<< count</code> <span class="emphasis"><em>stores</em></span> the amount returned by <code class="literal">count</code> to to the associated value of the corresponding <code class="command">execname()</code> in the <code class="literal">reads</code> array. Remember, these values are <span class="emphasis"><em>stored</em></span>; 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 (<code class="command">execname()</code>) having multiple associated values, accumulating with each probe handler run.
</div><div class="note"><h2>Note</h2><div class="para">
In the context of <a class="xref" href="arrayops-aggregates.html#simpleaggregates" title="Example 3.19. stat-aggregates.stp">Example 3.19, “stat-aggregates.stp”</a>, <code class="literal">count</code> returns the amount of data written by the returned <code class="command">execname()</code> to the virtual file system.
</div></div><a id="id3091223" class="indexterm"></a><a id="id2992799" class="indexterm"></a><a id="id3113929" class="indexterm"></a><a id="id2726562" class="indexterm"></a><a id="id2807267" class="indexterm"></a><div class="para">
To extract data collected by statistical aggregates, use the syntax format <code class="command">@<em class="replaceable"><code>extractor</code></em>(<em class="replaceable"><code>variable/array index expression</code></em>)</code>. <code class="command"><em class="replaceable"><code>extractor</code></em></code> can be any of the following integer extractors:
</div><div class="variablelist"><dl><dt><span class="term">count</span></dt><dd><a id="id2948888" class="indexterm"></a><a id="id4363511" class="indexterm"></a><a id="id2874016" class="indexterm"></a><a id="id3109551" class="indexterm"></a><div class="para">
Returns the number of all values stored into the variable/array index expression. Given the sample probe in <a class="xref" href="arrayops-aggregates.html#simpleaggregates" title="Example 3.19. stat-aggregates.stp">Example 3.19, “stat-aggregates.stp”</a>, the expression <code class="command">@count(writes[execname()])</code> will return <span class="emphasis"><em>how many values are stored</em></span> in each unique key in array <code class="literal">writes</code>.
</div></dd><dt><span class="term">sum</span></dt><dd><a id="id4349109" class="indexterm"></a><a id="id3092346" class="indexterm"></a><a id="id3003392" class="indexterm"></a><a id="id2994406" class="indexterm"></a><div class="para">
Returns the sum of all values stored into the variable/array index expression. Again, given sample probe in <a class="xref" href="arrayops-aggregates.html#simpleaggregates" title="Example 3.19. stat-aggregates.stp">Example 3.19, “stat-aggregates.stp”</a>, the expression <code class="command">@sum(writes[execname()])</code> will return <span class="emphasis"><em>the total of all values stored</em></span> in each unique key in array <code class="literal">writes</code>.
</div></dd><dt><span class="term">min</span></dt><dd><a id="id2937978" class="indexterm"></a><a id="id2995230" class="indexterm"></a><a id="id3087696" class="indexterm"></a><a id="id3042856" class="indexterm"></a><div class="para">
Returns the smallest among all the values stored in the variable/array index expression.
</div></dd><dt><span class="term">max</span></dt><dd><a id="id2928488" class="indexterm"></a><a id="id3065211" class="indexterm"></a><a id="id2819003" class="indexterm"></a><a id="id2937965" class="indexterm"></a><div class="para">
Returns the largest among all the values stored in the variable/array index expression.
</div></dd><dt><span class="term">avg</span></dt><dd><a id="id2753916" class="indexterm"></a><a id="id2969242" class="indexterm"></a><a id="id3094765" class="indexterm"></a><a id="id2691469" class="indexterm"></a><div class="para">
Returns the average of all values stored in the variable/array index expression.
</div></dd></dl></div><div class="para">
When using statistical aggregates, you can also build array constructs that use multiple index expressions (to a maximum of 5). This is helpful in capturing additional contextual information during a probe. For example:
</div><div class="example" id="multiplearrayindices"><div class="example-contents"><pre class="programlisting">
global reads
probe vfs.read
{
reads[execname(),pid()] <<< 1
}
probe timer.s(3)
{
foreach([var1,var2] in reads)
printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2]))
}
</pre></div><h6>Example 3.20. Multiple Array Indexes</h6></div><br class="example-break" /><div class="para">
In <a class="xref" href="arrayops-aggregates.html#multiplearrayindices" title="Example 3.20. Multiple Array Indexes">Example 3.20, “Multiple Array Indexes”</a>, the first probe tracks how many times each process performs a VFS read. What makes this different from earlier examples is that this array associates a performed read to both a process name <span class="emphasis"><em>and</em></span> its corresponding process ID.
</div><div class="para">
The second probe in <a class="xref" href="arrayops-aggregates.html#multiplearrayindices" title="Example 3.20. Multiple Array Indexes">Example 3.20, “Multiple Array Indexes”</a> demonstrates how to process and print the information collected by the array <code class="literal">reads</code>. Note how the <code class="command">foreach</code> statement uses the same number of variables (i.e. <code class="literal">var1</code> and <code class="literal">var2</code>) contained in the first instance of the array <code class="literal">reads</code> from the first probe.
</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="arrayops-conditionals.html"><strong>Prev</strong>3.5.6. Using Arrays in Conditional Statements</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="understanding-tapsets.html"><strong>Next</strong>3.6. Tapsets</a></li></ul></body></html>
distrib
>
Fedora
>
13
>
i386
>
media
>
os
>
by-pkgid
>
95299258dbdf9a86cefd89b97c0d81e5
>
files
>
90
