[About] [News] [Documentation] [Screenshots]

bugle-statistics — specify formulae and metadata for bugle statistics

"" =`name`

{ precision`expression`

label "`1`

" max`label`

}`100`

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*.

- signals
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
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`

`E`

/
`E`

*
`F`

means
“`F`

`E`

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

to be used as the value if the numerical value was`label`

`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.