kamailio/modules/debugger/doc/debugger_admin.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>

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

<chapter>
    
    <title>&adminguide;</title>
    
    <section>
	<title>Overview</title>
	<para>
		This module provides an interactive config file debugger. It can print
		a trace of config execution for a SIP message to log and set
		breakpoints on every config action, allowing step-by-step execution of 
		the config.
	</para>
	<para>
		Debugging can be done from local or remote host via RPC interface (e.g.,
		XMLRPC, sercmd, siremis).
	</para>
	<para>
		The framework to set breakpoints on specific actions and config lines
		is not exported to RPC yet. Each action can be accompanied by an
		breakpoint or you can use dbg_breakpoint() function to set a breakpoint
		at certain line. Global breakpoint can be enabled/disabled at runtime.
		Also the config running trace can be enabled/disabled at runtime.
	</para>
	<para>
		When the SIP router process is stopped at a breakpoint, you can
		investigate the values of any pseudo-variables. Note that some of
		pseudo-variables may produce memory leaks; a fix is planned in the
		future (here fall pseudo-variables with dynamic name such as htable,
		sqlops). References to SIP message, avps, headers, script and shared
		variables are safe.
	</para>
    </section>
    <section>
	<title>Dependencies</title>
	<section>
	    <title>&kamailio; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>none</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
	<section>
	    <title>External Libraries or Applications</title>
	    <para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>None</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Exported Parameters</title>
	<section>
	    <title><varname>cfgtrace</varname> (int)</title>
	    <para>
			Control whether config running trace is enabled or disabled
			at startup. You can change the value at runtime without
			restart, globally or per process.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>0</quote> (disabled).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>cfgtrace</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "cfgtrace", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>breakpoint</varname> (int)</title>
	    <para>
			Control whether every line (global) breakpoint is enabled
			or disabled at startup.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>0</quote> (disabled).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>breakpoint</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "breakpoint", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>log_level</varname> (int)</title>
	    <para>
			What log level is to be used to print module-specific messages.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>-1</quote> (L_ERR).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>log_level</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "log_level", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>log_facility</varname> (str)</title>
	    <para>
			What log facility is to be used to print module-specific messages.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>NULL</quote> (default from core).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>log_facility</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "log_facility", "LOG_DAEMON")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>log_prefix</varname> (str)</title>
	    <para>
			String to print before any module-specific messages.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>*** cfgtrace:</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>log_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "log_prefix", "from-debugger-with-love:")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>step_usleep</varname> (int)</title>
	    <para>
			Microseconds to sleep before checking for new commands when
			waiting at breakpoint.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>100000</quote> (that is 0.1 sec).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>step_usleep</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "step_usleep", 500000)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>step_loops</varname> (int)</title>
	    <para>
			How many sleeps of 'step_usleep' the RPC process performs when
			waiting for a reply from worker process before responding to RPC.
			This avoids blocking RPC process forever in case the worker
			process 'forgets' to write back a reply.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>200</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>step_loops</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("debugger", "step_loops", 100)
...
</programlisting>
	    </example>
	</section>

	</section>
	
    <section>
	<title>Exported Functions</title>
 	<section>
	    <title>
		<function moreinfo="none">dbg_breakpoint(mode)</function>
	    </title>
	    <para>
			Anchor a breakpoint at the current line of the config (the one
			on which this function is called). The 'mode' specifies whether 
			the breakpoint is enabled (1) or disabled (0) at startup.
	    </para>
		<para>
			Note that this version does not export this anchors to RPC for
			interactive debugging (temporarily disabled).
	    </para>
		<example>
		<title><function>dbg_breakpoint</function> usage</title>
		<programlisting format="linespecific">
...
if($si=="10.0.0.10")
	dbg_breakpoint("1");
...
</programlisting>
	    </example>
	</section>
	
    </section>
	
	<section>
		<title>Exported RPC Functions</title>

	<section>
		<title>
		<function moreinfo="none">dbg.ls</function>
		</title>
		<para>
			List SIP router processes with info related to interactive
			debugging.
		</para>
		<para>
		Name: <emphasis>dbg.list</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_pid_ : pid for which to list the details.  If 'pid' is
			omitted then will print for all processes.</para></listitem>	  
		</itemizedlist>
		<para>
		Examples of use with sercmd:
		</para>
        <programlisting  format="linespecific">
		dbg.ls
		dbg.ls 1234
		</programlisting>
    </section>

	<section>
		<title>
		<function moreinfo="none">dbg.trace</function>
		</title>
		<para>
			Control config running trace.
		</para>
		<para>
		Name: <emphasis>dbg.trace</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_cmd_ : inner command can be 'on' or 'off' to
				enable or disable tracing for one or all processes.</para>
		</listitem>
			<listitem><para>_pid_ : pid for which to list the details. If 'pid' is
				omitted, then it will print details for all processes.</para>
		</listitem>
		</itemizedlist>
		<para>
		Examples for using with sercmd:
		</para>
        <programlisting  format="linespecific">
		dbg.trace on
		dbg.trace off
		dbg.trace on 1234
		</programlisting>
    </section>

	<section>
		<title>
		<function moreinfo="none">dbg.bp</function>
		</title>
		<para>
			Control breakpoints and config execution.
		</para>
		<para>
		Name: <emphasis>dbg.bp</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_cmd_ : inner command, see next section for
			the list of available values.</para>
		</listitem>
		<listitem><para>_pid_ : pid for which to apply the inner command.
				If 'pid' is omitted, then the inner command will be applied 
				to all processes.</para>
		</listitem>
		<listitem><para>_params_ : extra params specific for each inner
				command.</para>
		</listitem>
		</itemizedlist>
		<para>Inner commands:</para>
		<itemizedlist>
		<listitem>
			<para>on - turn on breakpoints. Pid parameter is optional.
			</para>
		</listitem>
		<listitem>
			<para>off - turn off breakpoints. Pid parameter is optional.
			</para>
		</listitem>
		<listitem>
			<para>keep - keep breakpoints only for pid given as parameter
			</para>
		</listitem>
		<listitem>
			<para>release - disable breakpoints for processes that are
			not waiting at a breakpoint. Pid parameter is optional.</para>
		</listitem>
		<listitem>
			<para>next - run the action under breakpoint and stop at next one
			(step by step execution). Pid parameter is mandatory.
			</para>
		</listitem>
		<listitem>
			<para>move - run the action under breakpoint and remove the rest
			of breakpoints (continue execution without stopping again at next
			actions). Pid parameter is mandatory.</para>
		</listitem>
		<listitem>
			<para>show - print details about the current breakpoint for pid.
			Pid parameter is mandatory.</para>
		</listitem>
		<listitem>
			<para>eval - eval a pseudo-variable and print the result in RPC
			Pid parameter is mandatory.</para>
		</listitem>
		<listitem>
			<para>log - eval a pseudo-variable and print the result in SIP
			router logs. Pid parameter is mandatory.</para>
		</listitem>
		</itemizedlist>
		<para>
		Examples for using with sercmd:
		</para>
        <programlisting  format="linespecific">
		dbg.bp off
		dbg.bp on
		dbg.bp release
		dbg.bp on 1234
		dbg.bp eval 1234 $fu
		dbg.bp move 1234
		</programlisting>
    </section>

    </section>
	<section>
		<title>Usage</title>
		<para>
		A common usage is to investigate the execution path for a specific
		SIP message. Just enable cfg running trace, send the message and
		watch the logs.
		</para>
		<para>
		Another typical usage is to do interactive debugging and run
		each line of the route blocks of the config file step-by-step for a
		particular SIP message.
		</para>
		<para>
		You need to connect using sercmd (or other RPC client) to SIP Router.
		Then you can enable cfg breakpoints and send the SIP message. One
		process will be in waiting state ('state' field different than 0 when
		you do dbg.ls). Calling dbg.release will set the other SIP router
		processes in no-breakpoint mode so they can process other SIP messages
		without need to interact with them.
		</para>
		<para>
		The process blocked at breakpoint is waiting for a command. Use
		'dbg.bp next pid' to execute the current action and stop at the next
		one. 'dbg.bp eval pid PV' can be used to retrive the value of PV. Once
		you are done and want to continue the execution of the config wihtout
		interaction use 'dbg.bp move pid'.
		</para>
		<para>
		Here is an example of session:
		</para>
<programlisting  format="linespecific">
...
sercmd> dbg.ls
{
	entry: 0
	pid: 6393
	set: 3
	state: 0
	in.pid: 0
	in.cmd: 0
}
{
	entry: 1
	pid: 6394
	set: 3
	state: 0
	in.pid: 0
	in.cmd: 0
}
...
{
	entry: 9
	pid: 6402
	set: 3
	state: 1
	in.pid: 0
	in.cmd: 0
}

sercmd> dbg.bp show 6402
at bkp [/etc/kamailio/debugger.cfg:369] a=6 n=route

sercmd> dbg.bp next 6402
exec [/etc/kamailio/debugger.cfg:369] a=6 n=route

sercmd> dbg.bp next 6402
exec [/etc/kamailio/debugger.cfg:462] a=17 n=if

sercmd> dbg.bp eval 6402 $fu
$fu : t=str v=sip:[email protected]

sercmd> dbg.bp move 6402
200 ok
...
</programlisting>
		<para>
		Running the config trace looks like:
		</para>
<programlisting  format="linespecific">
...
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=368 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=461 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=456 a=26 n=mf_process_maxfwd_header
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=466 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=461 a=27 n=sanity_check
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=371 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=659 a=3 n=return
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=374 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=501 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=470 a=25 n=has_totag
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=386 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=379 a=26 n=is_method
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=386 a=25 n=t_check_trans
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=389 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=643 a=3 n=return
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=393 a=26 n=remove_hf
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=398 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=394 a=26 n=is_method
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=404 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=398 a=26 n=is_method
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=404 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=682 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=409 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=575 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=550 a=26 n=is_method
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=551 a=3 n=return
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=412 a=6 n=route
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=518 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=505 a=26 n=is_method
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=513 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=507 a=42 n=isflagset
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=516 a=17 n=if
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=513 a=26 n=save
 9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=516 a=3 n=exit
...
</programlisting>
		<para>
			The above example is for registration with default config for
			version 3.1.0, without authentication. Listed fields are:
			'c' - config file; 'l' - line; 'a' - internal action id;
			'n' - name of executed action. 'ERROR' prefix is printed
			because these messages were sent to the L_ERR log level.
		</para>
    </section>

</chapter>