bugle-statistics — specify formulae and metadata for bugle statistics
"name
" =expression
{ precision1
label "label
" max100
}
By default, bugle(3) gets statistics from
~/.bugle/statistics
, although an alternative
location may be specified in the BUGLE_STATISTICS
environment variable. Most users will just copy the sample file
doc/examples/statistics
from the source
distribution. This manual page describes the format in more detail
for those who want to set up custom statistics.
In order to understand bugle's statistics system, one must first understand how it uses signals and statistics.
A signal is a raw count of something, like number of frames, memory use, or load. For events, these are usually the total number of that event (like frame changes), rather than a rate. Signals are produced by generator filter-sets like bugle-stats_basic(7) or bugle-stats_primitives(7).
Statistics are high-level information computed from signals. For example, frame rate is computed from the number of frames signal and the time signal. Statistics also contain some metadata, such as the label to display with the statistic, and the number of significant digits to print. Logging filter-sets (bugle-logstats(7) and bugle-showstats(7)) use this information to display the statistics.
The statistics file contains the formulae used to compute statistics from signals, as well as the metadata mentioned above.
Blank lines and lines beginning with a #
are
ignored. Statistics have the basic format shown in the synopsis.
The expression consists of standard arithmetic operations
(including parentheses), numbers, and signal expressions. When a
signal expression is evaluated, it is done so over some interval
of time (usually one frame), but key_accumulate
in bugle-showstats(7) allows for longer intervals). Several types of
signal expressions are available to determine how the signal is
measured over that time:
d("signal
")
measures the change in the signal over the interval
a("signal
")
measures the average value of the signal during the interval
s("signal
")
measures the value at the start of the interval
e("signal
")
measures the value at the end of the interval
For measuring rates, use the ratio of two d
expressions. For example, the default configuration defines the
frame rate as
"frames per second" = d("frames") / d("seconds") { precision 1 label "fps" }
For statistics not defined by rates (such as memory consumption),
an a
expression is generally sufficient.
Expressions are evaluated using floating-point arithmetic,
applying the usual rules of operator precedence. If an
expression evaluates to a non-finite value (infinity or
NaN) it will not be shown at all. A non-obvious
application this is that given two expressions
E
and F
, the
compound expression
means
“E
/
E
*
F
F
unless
E
is zero”.
The lines between the {
and
}
contain metadata. The metadata keywords are:
precision
digits
the number of digits to show after the decimal point
label
"text
"the text to show with the statistic when logging
max
number
a maximum value for the statistic, used to scale graphs to the correct height
substitute
number
"label
"
causes label
to be used as
the value if the numerical value was
number
A *
may be used in the name of a signal. If
the expression for a statistic contains any wildcards, it is a
wildcard statistic. When a wildcard
statistic is selected for logging, it is instantiated zero or
more times, with every possible replacement for the wildcard
which yields a valid expression (in the sense that all the
resulting signals must exist). If *
appears
several times in the expression, all occurrences are replaced
with the same value in each instance.
In order to differentiate the instanced statistics, a
*
may also appear in the
label
. This is again replaced with the same
string used to replace the wildcards in the expressions.
For an example of a wildcard statistic in practise, see the
calls per frame
statistic in the
sample statistics file.