# &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 MI 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:

- -3 - L_ALERT

- -2 - L_CRIT

- -1 - L_ERR

- 1 - L_WARN

- 2 - L_NOTICE

- 3 - L_INFO

- 4 - L_DBG

Default value is 3 (L_INFO).

#### Set `loglevel` parameter

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

This will set the logging level to L_DBG.

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

## MI Commands

### `bm_enable_global`

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

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

    ...
    &ctltool; fifo bm_enable_timer test 1
    ...

### `bm_granularity`

Modifies the benchmarking granularity. See "granularity" variable.

### `bm_loglevel`

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

## Example of usage

Measure the duration of user location lookup.

### benchmark usage

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