Histogram Extractors; Hist_Linear - Red Hat ENTERPRISE LINUX 5.4 - SYSTEMTAP LANGUAGE Reference Manual

Chapter 8. Statistics (aggregates)

8.4. Histogram extractors

The following functions provide methods to extract histogram information. Printing a histogram with the
print family of functions renders a histogram object as a tabular "ASCII art" bar chart.

8.4.1. @hist_linear

The statement @hist_linear(v,L,H,W) represents a linear histogram v, where L and H represent
the lower and upper end of a range of values and W represents the width (or size) of each bucket
within the range. The low and high values can be negative, but the overall difference (high minus low)
must be positive. The width parameter must also be positive.
In the output, a range of consecutive empty buckets may be replaced with a tilde (~) character. This
can be controlled on the command line with -DHIST_ELISION=<num>, where <num> specifies
how many empty buckets at the top and bottom of the range to print. The default is 2. A <num> of 0
removes all empty buckets. A negative <num> turns off bucket removal all together.
For example, if you specify -DHIST_ELISION=3 and the histogram has 10 consecutive empty buckets,
the first 3 and last 3 empty buckets will be printed and the middle 4 empty buckets will be represented
by a tilde (~).
The following is an example.
global reads
probe netdev.receive {
reads <<< length
}
probe end {
print(@hist_linear(reads, 0, 10240, 200))
}
This generates the following output.
value |-------------------------------------------------- count
0 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 1650
200 |
400 |
600 |
~
1000 |
1200 |
1400 |
1600 |
1800 |
This shows that 1650 network reads were of a size between 0 and 200 bytes, 8 reads were between
200 and 400 bytes, and 1 read was between 1200 and 1400 bytes. The tilde (~) character indicates
buckets 700, 800 and 900 were removed because they were empty. Empty buckets at the upper end
were also removed.
36
8
0
0
0
0
1
0
0