BENCHMARK module

Admin Guide

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 OpenSIPS’s logging facility. Please note that all durations are given as microseconds (don’t confuse with milliseconds!).

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

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

Example of usage

Measure the duration of user location lookup.

benchmark usage

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

Developer Guide

The benchmark module provides an internal API to be used by other OpenSIPS modules. The available functions are identical to the user exported functions.

Please note that this module is intended mainly for developers. It should be used with caution in production environments.

Available Functions

bm_register(name, mode, id)

This function register a new timer and/or returns the internal ID associated with the timer. mode controls the creation of new timer if not found. id is to be used by start and log timer functions.

bm_start(id)

This function equals the user-exported function bm_start_timer. The id is passed as an integer, though.

bm_log(id)

This function equals the user-exported function bm_log_timer. The id is passed as an integer, though.

Benchmark API Example

Using the benchmark module's API from another module

...
#include "../benchmark/benchmark.h"
...
struct bm_binds bmb;
...
...
/* load the benchmarking API */
if (load_bm_api( &bmb )!=0) {
    LM_ERR("can't load benchmark API\n");
    goto error;
}
...
...
/* Start/log timers during a (usually user-exported) module function */
bmp.bm_register("test", 1, &id)
bmb.bm_start(id);
do_something();
bmb.bm_log(id);
...

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Daniel-Constantin Mierla (@miconda)	23	10	1391	50
2.	Bogdan-Andrei Iancu (@bogdan-iancu)	11	9	65	41
3.	Stefan Darius (@dariusstefan)	9	5	349	39
4.	Henning Westerholt (@henningw)	6	4	12	11
5.	Konstantin Bokarius	3	1	3	5
6.	Razvan Crainea (@razvancrainea)	3	1	2	2
7.	Edson Gellert Schubert	3	1	0	92

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Jun 2026 - Jun 2026
3.	Bogdan-Andrei Iancu (@bogdan-iancu)	Jul 2007 - Jul 2008
4.	Daniel-Constantin Mierla (@miconda)	Jul 2007 - Mar 2008
5.	Konstantin Bokarius	Mar 2008 - Mar 2008
6.	Edson Gellert Schubert	Feb 2008 - Feb 2008
7.	Henning Westerholt (@henningw)	Aug 2007 - Dec 2007

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw).

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0