Document @variance in the stap.1 man page.

diff --git a/man/stap.1.in b/man/stap.1.in
index 491c1ea6457a33c61eb6f6a0e134c539416aec1f..a8b36ec8134c05a899770b77c3baf09875e1849e 100644 (file)
--- a/man/stap.1.in
+++ b/man/stap.1.in
@@ -1620,7 +1620,7 @@ Here is the set of extractor functions.  The first argument of each is
 the same style of lvalue used on the left hand side of the accumulate
 operation.  The
 .IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v) ", "
-@variance(v) extractor functions compute the
+@variance(v[, b]) extractor functions compute the
 number/total/minimum/maximum/average/variance
 of all accumulated values.  The resulting values are all simple
 integers.  Arrays containing aggregates may be sorted and iterated.
@@ -1628,6 +1628,36 @@ See the
 .BR foreach
 construct above.
 .PP
+
+Variance uses Welford's online algorithm.  The calculations are based
+on integer arithmetics, and so may suffer from low precision. To improve
+this, @variance(v[, b]) accepts an optional parameter b, the
+bit-shift, ranging from 0 (default) to 62, for internal scaling.  Only one
+value of bit-shift may be used with given global variable.  The bit-shift may
+affect the result significantly, here is an example:
+
+.SAMPLE
+$ stap -e \\
+> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x)) }'
+12
+$ stap --poison-cache -e \\
+> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x,1)) }'
+2
+$ python3 -c 'import statistics; print(statistics.variance([1, 2, 3, 4, 5]))'
+2.5
+$
+.ESAMPLE
+
+Negative variance signals overflow.  In some cases you might need to
+normalize your input data.  Following rule applies:
+
+.SAMPLE
+if
+@variance(v1, v2, ..., vN) = V
+then
+@variance(Xv1, Xv2, ..., XvN) = 2XV
+.ESAMPLE
+
 Histograms are also available, but are more complicated because they
 have a vector rather than scalar value.
 .I @hist_linear(v,start,stop,interval)