1. Overview

This module helps developers to benchmark their module functions. By adding
this module's functions via the configuration file or through its API, Kamailio
can log profiling information for every function.

The duration between calls to start_timer and log_timer is stored and logged
via Kamailio's logging facility. Please note that all durations are given as
microseconds (don't confuse with milliseconds!).

2. Dependencies

2.1. Kamailio Modules

The following modules must be loaded before this module:

No dependencies on other Kamailio modules.

2.2. External Libraries or Applications

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

None.

3. Parameters

3.1. enable (int)

Even when the module is loaded, benchmarking is not enabled
per default. This variable may have three different values:

-1 - Globally disable benchmarking

0 - Enable per-timer enabling. Single timers are inactive by default
and can be activated through the RPC interface as soon as that feature is
implemented.

1 - Globally enable benchmarking

Default value is “0”.

Example 1.1. Set enable parameter

...
modparam("benchmark", "enable", 1)
...

3.2. granularity (int)

Logging normally is not done for every reference to the log_timer()
function, but only every n'th call. n is defined through this variable.
A sensible granularity seems to be 100.

Default value is “1”.

Example 1.2. Set granularity parameter

...
modparam("benchmark", "granularity", 500)
...

3.3. loglevel (int)

Set the log level for the benchmark logs. These levels should be used:

-5 - L_ALERT

-4 - L_BUG

-3 - L_CRIT

-2 - L_CRIT (no prefix)

-1 - L_ERR

0 - L_WARN

1 - L_NOTICE

2 - L_INFO

3 - L_DBG

Default value is “3” (L_INFO).

Example 1.3. Set loglevel parameter

...
modparam("benchmark", "loglevel", 4)
...

This will set the logging level to L_DBG.

4. Functions

4.1.
bm_start_timer(name)

Start timer “name”. A later call to
“bm_log_timer()” logs this timer..

Example 1.4. bm_start_timer usage

...
bm_start_timer("test");
...

4.2.
bm_log_timer(name)

This function logs the timer with the given ID. The following data are
logged:

Last msgs is the number of calls in the last logging interval. This equals the granularity variable.

Last sum is the accumulated duration in the current logging interval (i.e. for the last “granularity” calls).

Last min is the minimum duration between start/log_timer calls during the last interval.

Last max - maximum duration.

Last average is the average duration between
bm_start_timer() and bm_log_timer() since the last logging.

Global msgs number of calls to log_timer.

Global sum total duration in microseconds.

Global min... You get the point. :)

Global max also obvious.

Global avg possibly the most interesting value.

Example 1.5. bm_log_timer usage

...
bm_log_timer("test");
...

5. Exported Variables

Exported pseudo-variables are listed in the next sections.

5.1. $BM_time_diff

$BM_time_diff - the time difference
elapsed between calls of bm_start_timer(name) and
bm_log_timer(name). The value is 0 if no bm_log_timer()
was called.

6. RPC Commands

6.1. benchmark.enable_global

Enables/disables the module. Parameter may be -1, 0 or 1. See
discription of "enable" parameter.

6.2. benchmark.enable_timer

Enable or disable a single timer. The following example enables
timer "test" (the second parameter must be 0 to disable):