<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		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.
	</para>
	<para>
		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!).
	</para>
	<para> 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)!!
	</para>
	</section>
	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &osips; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>

	<section id="param_enable" xreflabel="enable">
		<title><varname>enable</varname> (int)</title>
		<para>
			Even when the module is loaded, benchmarking is not enabled
			per default. This variable may have three different values:
			<itemizedlist>
			<listitem>
			<para>
				-1 - Globally disable benchmarking
			</para>
			</listitem>
			<listitem>
			<para>
				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.
			</para>
			</listitem>
			<listitem>
			<para>
				1 - Globally enable benchmarking
			</para>
			</listitem>
			</itemizedlist>
		</para>
		<para>
		<emphasis>
			Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>enable</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("benchmark", "enable", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_granularity" xreflabel="granularity">
		<title><varname>granularity</varname> (int)</title>
		<para>
			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.
		</para>
		<para>
			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.
		</para>
		<para>
		<emphasis>
			Default value is <quote>100</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>granularity</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("benchmark", "granularity", 500)
...
</programlisting>
		</example>
	</section>

	<section id="param_loglevel" xreflabel="loglevel">
		<title><varname>loglevel</varname> (int)</title>
		<para>
			Set the log level for the benchmark logs. These levels should be used:
			<itemizedlist>
			<listitem><para>-3 - L_ALERT</para></listitem>
			<listitem><para>-2 - L_CRIT</para></listitem>
			<listitem><para>-1 - L_ERR</para></listitem>
			<listitem><para>1 - L_WARN</para></listitem>
			<listitem><para>2 - L_NOTICE</para></listitem>
			<listitem><para>3 - L_INFO</para></listitem>
			<listitem><para>4 - L_DBG</para></listitem>
			</itemizedlist>
		</para>
		<para>
		<emphasis>
			Default value is <quote>3</quote> (L_INFO).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>loglevel</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("benchmark", "loglevel", 4)
...
</programlisting>
		</example>
		<para>
		This will set the logging level to L_DBG.
		</para>
	</section>

	</section>
	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_bm_start_timer" xreflabel="bm_start_timer()">
		<title>
		<function moreinfo="none">bm_start_timer(name)</function>
		</title>
		<para>
		Start timer <quote>name</quote>. A later call to
		<quote>bm_log_timer()</quote> logs this timer..
		</para>
		<example>
		<title><function>bm_start_timer</function> usage</title>
		<programlisting format="linespecific">
...
bm_start_timer("test");
...
</programlisting>
		</example>
	</section>

	<section id="func_bm_log_timer" xreflabel="bm_log_timer()">
		<title>
		<function moreinfo="none">bm_log_timer(name)</function>
		</title>
		<para>
			This function logs the timer with the given ID. The following data are
			logged:
			<itemizedlist>
				<listitem>
					<para><emphasis>Last msgs</emphasis> is the number of calls in the last logging interval. This equals the granularity variable.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Last sum</emphasis> is the accumulated duration in the current logging interval (i.e. for the last <quote>granularity</quote> calls).
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Last min</emphasis> is the minimum duration between start/log_timer calls during the last interval.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Last max</emphasis> - maximum duration.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Last average</emphasis> is the average duration between
					bm_start_timer() and bm_log_timer() since the last logging.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Global msgs</emphasis> number of calls to log_timer.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Global sum</emphasis> total duration in microseconds.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Global min</emphasis>... You get the point. :)
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Global max</emphasis> also obvious.
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<listitem>
					<para><emphasis>Global avg</emphasis> possibly the most interesting value.
					</para>
				</listitem>
			</itemizedlist>
		</para>
		<example>
		<title><function>bm_log_timer</function> usage</title>
		<programlisting format="linespecific">
...
bm_log_timer("test");
...
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_pseudo_variables">
		<title>Exported Pseudo-Variables</title>
		<para>
		Exported pseudo-variables are listed in the next sections.
		</para>
		<section id="pv_BM_time_diff" xreflabel="$BM_time_diff">
		<title>$BM_time_diff</title>
			<para>
			<emphasis>$BM_time_diff</emphasis> - 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.
			</para>
		</section>
	</section>

	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
		<title>Exported MI Functions</title>
		<section id="mi_bm_enable_global" xreflabel="bm_enable_global">
			<title><function moreinfo="none">bm_enable_global</function></title>
			<para>
				Enables/disables the module.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>enable</emphasis> - value may be -1, 0 or 1. See
					discription of "enable" parameter.
				</para></listitem>
			</itemizedlist>
			<para>
			MI FIFO Command Format:
			</para>
			<programlisting  format="linespecific">
			opensips-cli -x mi bm_enable_global 1
			</programlisting>
		</section>
		<section id="mi_bm_enable_timer" xreflabel="bm_enable_timer">
			<title><function moreinfo="none">bm_enable_timer</function></title>
			<para>
				Enable or disable a single timer.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>timer</emphasis> - timer name
				</para></listitem>
				<listitem><para>
					<emphasis>enable</emphasis> - enable (1) or disable (0) timer
				</para></listitem>
			</itemizedlist>
			<para>
			MI FIFO Command Format:
			</para>
			<example>
				<title>Enabling a timer</title>
				<programlisting format="linespecific">
...
opensips-cli -x mi bm_enable_timer test 1
...
</programlisting>
			</example>
		</section>
		<section id="mi_bm_granularity" xreflabel="bm_granularity">
			<title><function moreinfo="none">bm_granularity</function></title>
			<para>
				Modifies the benchmarking granularity.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>granularity</emphasis> - See
					discription of "granularity" parameter.
				</para></listitem>
			</itemizedlist>
			<para>
			MI FIFO Command Format:
			</para>
			<programlisting  format="linespecific">
			opensips-cli -x mi bm_granularity 300
			</programlisting>
		</section>
		<section id="mi_bm_loglevel" xreflabel="bm_loglevel">
			<title><function moreinfo="none">bm_loglevel</function></title>
			<para>
				Modifies the module log level.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>log_level</emphasis> - See
					discription of "loglevel" parameter.
				</para></listitem>
			</itemizedlist>
			<para>
			MI FIFO Command Format:
			</para>
			<programlisting  format="linespecific">
			opensips-cli -x mi bm_loglevel 4
			</programlisting>
		</section>
		<section id="mi_bm_poll_results" xreflabel="bm_poll_results">
			<title><function moreinfo="none">bm_poll_results</function></title>
			<para>
				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.
			</para>
			<para>
				If there were no new calls to <emphasis>bm_log_timer</emphasis> since last check, then all current values of a timer will be equal 0. Each call to <emphasis>bm_poll_results</emphasis> will reset current values (but not global ones).
			</para>
			<example>
				<title>Getting the results via FIFO interface</title>
				<programlisting format="linespecific">
...
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
...
</programlisting>
			</example>
		</section>
	</section>

	<section>
		<title>Example of usage</title>
		<para>
		Measure the duration of user location lookup.
		</para>
		<example>
			<title>benchmark usage</title>
			<programlisting format="linespecific">
...
bm_start_timer("usrloc-lookup");
lookup("location");
bm_log_timer("usrloc-lookup");
...
</programlisting>
		</example>
	</section>
</chapter>

