1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | <?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 xmlns:d="http://docbook.org/ns/docbook">3.5.7. Computing for Statistical Aggregates</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta xmlns:d="http://docbook.org/ns/docbook" name="generator" content="not publican" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="" /><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><p id="title"></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="arrayops-conditionals.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="understanding-tapsets.html"><strong>Next</strong></a></li></ul><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="arrayops-aggregates"> </a>3.5.7. Computing for Statistical Aggregates</h3></div></div></div><a id="id3897" class="indexterm"></a><a id="id3900" class="indexterm"></a><a id="id3903" class="indexterm"></a><a id="id3906" class="indexterm"></a><a id="id3909" 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 (that is, storing only aggregated stream statistics). Statistical aggregates can be used in global variables or as elements in an array.</div><a id="id3913" class="indexterm"></a><a id="id3917" class="indexterm"></a><a id="id3921" class="indexterm"></a><a id="id3925" class="indexterm"></a><div class="para">To add value to a statistical aggregate, use the operator <code class="command"><<< <em class="replaceable">value</em></code>.</div><div class="example"><a id="simpleaggregates"> </a><p class="title"><strong>Example 3.21. stat-aggregates.stp</strong></p><div class="example-contents"><pre class="programlisting">global reads probe vfs.read { reads[execname()] <<< $count }</pre></div></div><a id="id3936" class="indexterm"></a><a id="id3940" class="indexterm"></a><a id="id3944" class="indexterm"></a><a id="id3948" class="indexterm"></a><div class="para">In <a class="xref" href="arrayops-aggregates.html#simpleaggregates">Example 3.21, “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 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 xmlns:d="http://docbook.org/ns/docbook" class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">In the context of <a class="xref" href="arrayops-aggregates.html#simpleaggregates">Example 3.21, “stat-aggregates.stp”</a>, <code class="literal">count</code> returns the amount of data read by the returned <code class="command">execname()</code> to the virtual file system.</div></div></div><a id="id3967" class="indexterm"></a><a id="id3971" class="indexterm"></a><a id="id3975" class="indexterm"></a><a id="id3979" class="indexterm"></a><a id="id3983" class="indexterm"></a><div class="para">To extract data collected by statistical aggregates, use the syntax format <code class="command">@<em class="replaceable">extractor</em>(<em class="replaceable">variable/array index expression</em>)</code>. <code class="command"><em class="replaceable">extractor</em></code> can be any of the following integer extractors:</div><div class="variablelist"><dl class="variablelist"><dt><span class="term">count</span></dt><dd><a id="id3997" class="indexterm"></a><a id="id4001" class="indexterm"></a><a id="id4005" class="indexterm"></a><a id="id4009" 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">Example 3.21, “stat-aggregates.stp”</a>, the expression <code class="command">@count(reads[execname()])</code> will return <span class="emphasis"><em>how many values are stored</em></span> in each unique key in array <code class="literal">reads</code>. </div></dd><dt><span class="term">sum</span></dt><dd><a id="id4021" class="indexterm"></a><a id="id4025" class="indexterm"></a><a id="id4029" class="indexterm"></a><a id="id4033" 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">Example 3.21, “stat-aggregates.stp”</a>, the expression <code class="command">@sum(reads[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">reads</code>. </div></dd><dt><span class="term">min</span></dt><dd><a id="id4045" class="indexterm"></a><a id="id4049" class="indexterm"></a><a id="id4053" class="indexterm"></a><a id="id4057" 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="id4065" class="indexterm"></a><a id="id4069" class="indexterm"></a><a id="id4073" class="indexterm"></a><a id="id4077" 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="id4085" class="indexterm"></a><a id="id4089" class="indexterm"></a><a id="id4093" class="indexterm"></a><a id="id4097" 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"><a id="multiplearrayindices"> </a><p class="title"><strong>Example 3.22. Multiple Array Indexes</strong></p><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></div><div class="para"> In <a class="xref" href="arrayops-aggregates.html#multiplearrayindices">Example 3.22, “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">Example 3.22, “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 (that is, <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>
|
