# &adminguide;

## 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!).

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- No dependencies on other &kamailio; modules.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None.

## Parameters

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

#### Set `enable` parameter

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

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

#### Set `granularity` parameter

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

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

#### Set `loglevel` parameter

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

This will set the logging level to L_DBG.

### `register` (str)

Register a timer id at startup. Required when using the start/log functions via Kemi framework. This parameter can be set many times to register several timer ids.

Default value is NONE.

#### Set `register` parameter

    ...
    modparam("benchmark", "register", "test")
    modparam("benchmark", "register", "auth")
    ...

## Functions

### `bm_start_timer(name)`

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

#### `bm_start_timer` usage

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

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

#### `bm_log_timer` usage

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

## Exported Variables

Exported pseudo-variables are listed in the next sections.

### $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.

## RPC Commands

### `benchmark.enable_global`

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

### `benchmark.enable_timer`

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

#### Enabling a timer

    ...
    &kamcmd; benchmark.enable_timer test 1
    ...

### `benchmark.granularity`

Modifies the benchmarking granularity. See "granularity" variable.

### `benchmark.loglevel`

Modifies the module log level. See "loglevel" variable.

### `benchmark.timer_list`

List data for all timers (Last complete period and global data) Displays info close to the one output in the log by using a RPC structure. period_sum, period_min and period_media show data for last granularity period already completed.

#### List all timers

    ...
    &kamcmd; benchmark.timer_list
    {
    	name: test
    	state: enabled
    	id: 0
    	granularity: 2
    	period_sum: 69
    	period_min: 22
    	period_max: 47
    	period_media: 34.500000
    	calls: 4
    	sum: 217
    	global_min: 22
    	global_max: 88
    	global_media: 54.250000
    }
    {
    	name: test2
    	state: enabled
    	id: 1
    	granularity: 2
    	period_sum: 122
    	period_min: 25
    	period_max: 97
    	period_media: 61.000000
    	calls: 4
    	sum: 349
    	global_min: 25
    	global_max: 151
    	global_media: 87.250000
    }
    ...

### `benchmark.timer_name_list`

List data for one timer based on its name (Last complete period and global data) It displays info close to the one output in the log by using a RPC structure. period_sum, period_min and period_media show data for last granularity period already completed.

#### List one timer

    ...
    &kamcmd; benchmark.timer_name_list test
    {
    	name: test
    	state: enabled
    	id: 0
    	granularity: 2
    	period_sum: 69
    	period_min: 22
    	period_max: 47
    	period_media: 34.500000
    	calls: 4
    	sum: 217
    	global_min: 22
    	global_max: 88
    	global_media: 54.250000
    }
    ...

## Example of usage

Measure the duration of user location lookup.

### benchmark usage

    ...
    bm_start_timer("usrloc-lookup");
    lookup("location");
    bm_log_timer("usrloc-lookup");
    ...