STATISTICS module

Admin Guide

Overview

The Statistics module is a wrapper over the internal statistics manager, allowing the script writer to dynamically define and use of statistic variables.

By bringing the statistics support into the script, it takes advantage of the script flexibility in defining logics, making possible implementation of any kind of statistic scenario.

Statistic Groups

Starting with OpenSIPS 2.3, statistics may be grouped by prefixing their names with the name of the desired group, along with a colon separator (e.g. $stat(method:invite) or update_stat(“packets:$var(ptype)”, “+1”)). In order for this to work, the groups must be defined prior to OpenSIPS startup using the stat groups module parameter.

The module allows easy iteration over the statistics of a group using the stat iter init and stat iter next functions.

By default, all statistics belong to the “dynamic” group.

Statistic Series

Statistic series provide the ability to accumulate statistical data over a pre-defined time window. Data is stored in a circular buffer, pushing new data on top, and removing stale values (values outside the timeframe) from the bottom. These statistics can be used to provide per-time stats, such as ACD, ASR, AST, etc, that can be read using the classic statistics interface, through the $stat() variable.

Statistic series profile describe the timeframe used to store the data, as well as how the data is be accumulated and interpreted. There are several types a statistic series can be used, depending on the provisioned algorithm:

accumulate - accumulates the specified values in a counter; works similar to clasical statistics, except that they reset after the specified timeframe
average - returns an average of all the data fed within the timeframe; can be useful when computing PDD, AST, ACD stats.
percentage - indicates the percentage of a set of values out of the total amount of values fed; can be useful when computing ASR, NER, CCR stats.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

No dependencies on other OpenSIPS modules.

External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

None.

Exported Parameters

variable (string)

Name of a new statistic variable. The name may be followed by additional flag which describe the variable behavior:

no_reset : variable cannot be reset.

modparam("statistics", "variable", "register_counter")
modparam("statistics", "variable", "active_calls/no_reset")

stat_groups (string)

A comma-separated values string, specifying the statistic groups that may be used throughout the OpenSIPS script. Groups cannot contain leading or trailing whitespace characters.

modparam("statistics", "stat_groups", "method, packet, response")

stat_series_profile (string)

Used to define a statistic series profile. Has the following format: *name: [attr=value]**, where name represents the name of the profile, and attr=value contains multiple settings of the defined profile. Possible attributes and their values are:

algorithm - indicates the way data should be stored and accumulated over the specified timeframe. Possible values are: accumulate, average and percentage, as described in the section stat series paragraph (default is accumulate)
hash_size - each statistic defined/used is stored in a hash map attached to the profile; this setting tunes the size of the hash (default is: 8)
group - indicates the group where the statistics beloging to this profile are grouped (as described in stat groups (default is to use the same group as the profile)
window - the number of seconds a timeframe has; all older values (out of the specified window) are discarded (default is 60 seconds)
slots - the number of slots per window; used to tune the granularity of the circular buffer; the higher the number of slots is, the more accurate the resulted statistic; (default is the same value of the window parameter)
percentage_factor - used for percentage algorithm profiles to specify the percentage factor to be used (defaults to 100)

This parameter can be set multiple times, for each profile needed.

...
# define a statistic that accumulates average values in the last minute
modparam("statistics", "stat_series_profile", "avg: algorithm=average")
...
# define a statistic that accumulates average values in the 10 minutes
# with 1 minute granularity (10 slots out of the 600s window)
modparam("statistics", "stat_series_profile", "avg_10m: algorithm=average window=600 slots=10")
...
# define a statistic that computes the percentage of values in the last hour
# with 10 minutes granularity (6 slots out of the 3600s window)
modparam("statistics", "stat_series_profile", "perc_1h: algorithm=percentage window=3600 slots=6")
...