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 | 8 400 | 0 600 | 0 ~ 1000 | 0 1200 | 0 1400 | 1 1600 | 0 1800 | 0
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.
8.4.2. @hist_log
The statement
@hist_log(v) represents a base-2 logarithmic histogram. Empty buckets are replaced with a tilde (~) character in the same way as @hist_linear() (see above).
The following is an example.
global reads
probe netdev.receive {
reads <<< length
}
probe end {
print(@hist_log(reads))
}
This generates the following output.
value |-------------------------------------------------- count 8 | 0 16 | 0 32 | 254 64 | 3 128 | 2 256 | 2 512 | 4 1024 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 16689 2048 | 0 4096 | 0
