Benchmark Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. enable (int)
              1.3.2. granularity (int)
              1.3.3. loglevel (int)

        1.4. Exported Functions

              1.4.1. bm_start_timer(name)
              1.4.2. bm_log_timer(name)

        1.5. Exported Pseudo-Variables

              1.5.1. $BM_time_diff

        1.6. Exported MI Functions

              1.6.1. bm_enable_global
              1.6.2. bm_enable_timer
              1.6.3. bm_granularity
              1.6.4. bm_loglevel
              1.6.5. bm_poll_results

        1.7. Example of usage

   2. Developer Guide

        2.1. Available Functions

              2.1.1. bm_register(name, mode, id)
              2.1.2. bm_start(id)
              2.1.3. bm_log(id)

        2.2. Benchmark API Example

   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set enable parameter
   1.2. Set granularity parameter
   1.3. Set loglevel parameter
   1.4. bm_start_timer usage
   1.5. bm_log_timer usage
   1.6. Enabling a timer
   1.7. Getting the results via FIFO interface
   1.8. benchmark usage
   2.1. Using the benchmark module's API from another module

Chapter 1. Admin Guide

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

   Important note: as this benchmarking is intended to measure the
   time spent in executing different parts/blocks of the script
   (and not for measuring the time induced by the SIP signaling),
   the benchmark module is to be used within the SAME top route
   (request route, failure route, branch route, onreply rout,
   etc). It is not design to be used across different types of top
   routes (like started in request route and ended in failure
   route)!!

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * No dependencies on other OpenSIPS modules.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Parameters

1.3.1. 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”.

   Example 1.1. Set enable parameter
...
modparam("benchmark", "enable", 1)
...

1.3.2. 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”.

   Example 1.2. Set granularity parameter
...
modparam("benchmark", "granularity", 500)
...

1.3.3. 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).

   Example 1.3. Set loglevel parameter
...
modparam("benchmark", "loglevel", 4)
...

   This will set the logging level to L_DBG.

1.4. Exported Functions

1.4.1.  bm_start_timer(name)

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

   Example 1.4. bm_start_timer usage
...
bm_start_timer("test");
...

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

   Example 1.5. bm_log_timer usage
...
bm_log_timer("test");
...

1.5. Exported Pseudo-Variables

   Exported pseudo-variables are listed in the next sections.

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

1.6. Exported MI Functions

1.6.1. bm_enable_global

   Enables/disables the module.

   Parameters:
     * enable - value may be -1, 0 or 1. See discription of
       "enable" parameter.

   MI FIFO Command Format:
                        opensips-cli -x mi bm_enable_global 1

1.6.2. bm_enable_timer

   Enable or disable a single timer.

   Parameters:
     * timer - timer name
     * enable - enable (1) or disable (0) timer

   MI FIFO Command Format:

   Example 1.6. Enabling a timer
...
opensips-cli -x mi bm_enable_timer test 1
...

1.6.3. bm_granularity

   Modifies the benchmarking granularity.

   Parameters:
     * granularity - See discription of "granularity" parameter.

   MI FIFO Command Format:
                        opensips-cli -x mi bm_granularity 300

1.6.4. bm_loglevel

   Modifies the module log level.

   Parameters:
     * log_level - See discription of "loglevel" parameter.

   MI FIFO Command Format:
                        opensips-cli -x mi bm_loglevel 4

1.6.5. 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).

   Example 1.7. Getting the results via FIFO interface
...
opensips-cli -x mi 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
...

1.7. Example of usage

   Measure the duration of user location lookup.

   Example 1.8. benchmark usage
...
bm_start_timer("usrloc-lookup");
lookup("location");
bm_log_timer("usrloc-lookup");
...

Chapter 2. 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.

2.1. Available Functions

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

2.1.2.  bm_start(id)

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

2.1.3.  bm_log(id)

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

2.2. Benchmark API Example

   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 */
bmb.bm_register("test", 1, &id)
bmb.bm_start(id);
do_something();
bmb.bm_log(id);
...

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Daniel-Constantin Mierla (@miconda) 23 10 1391 50
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 21 19 88 53
   3. Liviu Chircu (@liviuchircu) 12 10 28 59
   4. Razvan Crainea (@razvancrainea) 11 9 23 21
   5. Vlad Patrascu (@rvlad-patrascu) 9 4 185 143
   6. Stanislaw Pitucha 7 3 170 65
   7. Henning Westerholt (@henningw) 6 4 11 10
   8. David Sanders 4 2 8 1
   9. Anca Vamanu 3 1 5 2
   10. Konstantin Bokarius 3 1 3 5

   All remaining contributors: Peter Lemenkov (@lemenkov), Edson
   Gellert Schubert.

   (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. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

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

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - Nov 2019
   2.  Razvan Crainea (@razvancrainea)     Sep 2011 - Sep 2019
   3.  Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2007 - Apr 2019
   4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   5.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   6.  David Sanders                       Aug 2012 - Jan 2013
   7.  Anca Vamanu                         Sep 2009 - Sep 2009
   8.  Stanislaw Pitucha                   Aug 2009 - Sep 2009
   9.  Daniel-Constantin Mierla (@miconda) Jul 2007 - Mar 2008
   10. Konstantin Bokarius                 Mar 2008 - Mar 2008

   All remaining contributors: Edson Gellert Schubert, Henning
   Westerholt (@henningw).

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

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Razvan Crainea (@razvancrainea), Peter Lemenkov
   (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu
   (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu),
   Stanislaw Pitucha, Daniel-Constantin Mierla (@miconda),
   Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt
   (@henningw).

   Documentation Copyrights:

   Copyright © 2007 Collax GmbH

   Copyright © 2007 Voice Sistem SRL
