Table of Contents
List of Examples
enable parametergranularity parameterloglevel parameterregister parameterbm_start_timer usagebm_log_timer usageTable of Contents
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!).
The following modules must be loaded before this module:
No dependencies on other Kamailio modules.
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”.
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 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).
This will set the logging level to L_DBG.
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”.
Example 1.4. Set register parameter
...
modparam("benchmark", "register", "test")
modparam("benchmark", "register", "auth")
...
Start timer “name”. A later call to “bm_log_timer()” logs this timer..
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.
Exported pseudo-variables are listed in the next sections.
Enables/disables the module. Parameter may be -1, 0 or 1. See description of "enable" parameter.
Enable or disable a single timer. The following example enables timer "test" (the second parameter must be 0 to disable):
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.
Example 1.8. 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
}
...
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.
Example 1.9. 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
}
...
Table of Contents
The benchmark module provides an internal API to be used by other Kamailio 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.
This function registers 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.
This function equals the user-exported function bm_start_timer. The id is passed as an integer, though.
Example 2.1. 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);
...