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

Name

bugle-statistics — specify formulae and metadata for bugle statistics

Synopsis

"name" = expression
{
    precision 1
    label "label"
    max 100
}

Description

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.

Syntax

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 E / E * F means 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

Wildcards

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.

Files

~/.bugle/statistics

Formulae and metadata for statistics

Environment

BUGLE_STATISTICS

If set, defines the location of the statistics file, overriding the default above.

Author

bugle is written and maintained by Bruce Merry.


Get BuGLe at SourceForge.net. Fast, secure and Free Open Source software downloads