# &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, OpenSIPS can log profiling information for every function.

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

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- No dependencies on other &osips; modules.

### External Libraries or Applications

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

- None.

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

If granularity is set to 0, then nothing will be logged automatically. Instead bm_poll_results MI command can be used to retrieve the results and clean the local values.

Default value is 100.

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

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

## Exported MI Functions

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

    ...
    opensipsctl 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.

### `bm_poll_results`

Returns the current and global results for each timer. This command is only available if the "granularity" variable is set to 0. It can be used to get results in stable time intervals instead of every N messages. Each timer will have 2 nodes - the local and the global values. Format of the values is the same as the one normally used in logfile. This way of getting the results allows to interface with external graphing applications like Munin.

If there were no new calls to bm_log_timer since last check, then all current values of a timer will be equal 0. Each call to bm_poll_results will reset current values (but not global ones).

#### Getting the results via FIFO interface

    ...
    opensipsctl fifo bm_poll_results
    register_timer
    	3/40/12/14/13.333333
    	9/204/12/97/22.666667
    security_check_timer
    	3/21/7/7/7.000000
    	9/98/7/41/10.888889
    ...

## Example of usage

Measure the duration of user location lookup.

### benchmark usage

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