mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
441 lines
13 KiB
441 lines
13 KiB
debugger Module
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
asipto.com
|
|
|
|
Edited by
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. cfgtrace (int)
|
|
3.2. breakpoint (int)
|
|
3.3. log_level (int)
|
|
3.4. log_facility (str)
|
|
3.5. log_prefix (str)
|
|
3.6. step_usleep (int)
|
|
3.7. step_loops (int)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. dbg_breakpoint(mode)
|
|
|
|
5. Exported RPC Functions
|
|
|
|
5.1. dbg.ls
|
|
5.2. dbg.trace
|
|
5.3. dbg.bp
|
|
|
|
6. Usage
|
|
|
|
List of Examples
|
|
|
|
1.1. Set cfgtrace parameter
|
|
1.2. Set breakpoint parameter
|
|
1.3. Set log_level parameter
|
|
1.4. Set log_facility parameter
|
|
1.5. Set log_prefix parameter
|
|
1.6. Set step_usleep parameter
|
|
1.7. Set step_loops parameter
|
|
1.8. dbg_breakpoint usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. cfgtrace (int)
|
|
3.2. breakpoint (int)
|
|
3.3. log_level (int)
|
|
3.4. log_facility (str)
|
|
3.5. log_prefix (str)
|
|
3.6. step_usleep (int)
|
|
3.7. step_loops (int)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. dbg_breakpoint(mode)
|
|
|
|
5. Exported RPC Functions
|
|
|
|
5.1. dbg.ls
|
|
5.2. dbg.trace
|
|
5.3. dbg.bp
|
|
|
|
6. Usage
|
|
|
|
1. Overview
|
|
|
|
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.
|
|
|
|
Debugging can be done from local or remote host via RPC interface
|
|
(e.g., XMLRPC, sercmd, siremis).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* none.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None.
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. cfgtrace (int)
|
|
3.2. breakpoint (int)
|
|
3.3. log_level (int)
|
|
3.4. log_facility (str)
|
|
3.5. log_prefix (str)
|
|
3.6. step_usleep (int)
|
|
3.7. step_loops (int)
|
|
|
|
3.1. cfgtrace (int)
|
|
|
|
Control whether config running trace is enabled or disabled at startup.
|
|
You can change the value at runtime without restart, globally or per
|
|
process.
|
|
|
|
Default value is “0” (disabled).
|
|
|
|
Example 1.1. Set cfgtrace parameter
|
|
...
|
|
modparam("debugger", "cfgtrace", 1)
|
|
...
|
|
|
|
3.2. breakpoint (int)
|
|
|
|
Control whether every line (global) breakpoint is enabled or disabled
|
|
at startup.
|
|
|
|
Default value is “0” (disabled).
|
|
|
|
Example 1.2. Set breakpoint parameter
|
|
...
|
|
modparam("debugger", "breakpoint", 1)
|
|
...
|
|
|
|
3.3. log_level (int)
|
|
|
|
What log level is to be used to print module-specific messages.
|
|
|
|
Default value is “-1” (L_ERR).
|
|
|
|
Example 1.3. Set log_level parameter
|
|
...
|
|
modparam("debugger", "log_level", 1)
|
|
...
|
|
|
|
3.4. log_facility (str)
|
|
|
|
What log facility is to be used to print module-specific messages.
|
|
|
|
Default value is “NULL” (default from core).
|
|
|
|
Example 1.4. Set log_facility parameter
|
|
...
|
|
modparam("debugger", "log_facility", "LOG_DAEMON")
|
|
...
|
|
|
|
3.5. log_prefix (str)
|
|
|
|
String to print before any module-specific messages.
|
|
|
|
Default value is “*** cfgtrace:”.
|
|
|
|
Example 1.5. Set log_prefix parameter
|
|
...
|
|
modparam("debugger", "log_prefix", "from-debugger-with-love:")
|
|
...
|
|
|
|
3.6. step_usleep (int)
|
|
|
|
Microseconds to sleep before checking for new commands when waiting at
|
|
breakpoint.
|
|
|
|
Default value is “100000” (that is 0.1 sec).
|
|
|
|
Example 1.6. Set step_usleep parameter
|
|
...
|
|
modparam("debugger", "step_usleep", 500000)
|
|
...
|
|
|
|
3.7. step_loops (int)
|
|
|
|
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.
|
|
|
|
Default value is “200”.
|
|
|
|
Example 1.7. Set step_loops parameter
|
|
...
|
|
modparam("debugger", "step_loops", 100)
|
|
...
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. dbg_breakpoint(mode)
|
|
|
|
4.1. dbg_breakpoint(mode)
|
|
|
|
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.
|
|
|
|
Note that this version does not export this anchors to RPC for
|
|
interactive debugging (temporarily disabled).
|
|
|
|
Example 1.8. dbg_breakpoint usage
|
|
...
|
|
if($si=="10.0.0.10")
|
|
dbg_breakpoint("1");
|
|
...
|
|
|
|
5. Exported RPC Functions
|
|
|
|
5.1. dbg.ls
|
|
5.2. dbg.trace
|
|
5.3. dbg.bp
|
|
|
|
5.1. dbg.ls
|
|
|
|
List SIP router processes with info related to interactive debugging.
|
|
|
|
Name: dbg.list
|
|
|
|
Parameters:
|
|
* _pid_ : pid for which to list the details. If 'pid' is omitted then
|
|
will print for all processes.
|
|
|
|
Examples of use with sercmd:
|
|
dbg.ls
|
|
dbg.ls 1234
|
|
|
|
5.2. dbg.trace
|
|
|
|
Control config running trace.
|
|
|
|
Name: dbg.trace
|
|
|
|
Parameters:
|
|
* _cmd_ : inner command can be 'on' or 'off' to enable or disable
|
|
tracing for one or all processes.
|
|
* _pid_ : pid for which to list the details. If 'pid' is omitted,
|
|
then it will print details for all processes.
|
|
|
|
Examples for using with sercmd:
|
|
dbg.trace on
|
|
dbg.trace off
|
|
dbg.trace on 1234
|
|
|
|
5.3. dbg.bp
|
|
|
|
Control breakpoints and config execution.
|
|
|
|
Name: dbg.bp
|
|
|
|
Parameters:
|
|
* _cmd_ : inner command, see next section for the list of available
|
|
values.
|
|
* _pid_ : pid for which to apply the inner command. If 'pid' is
|
|
omitted, then the inner command will be applied to all processes.
|
|
* _params_ : extra params specific for each inner command.
|
|
|
|
Inner commands:
|
|
* on - turn on breakpoints. Pid parameter is optional.
|
|
* off - turn off breakpoints. Pid parameter is optional.
|
|
* keep - keep breakpoints only for pid given as parameter
|
|
* release - disable breakpoints for processes that are not waiting at
|
|
a breakpoint. Pid parameter is optional.
|
|
* next - run the action under breakpoint and stop at next one (step
|
|
by step execution). Pid parameter is mandatory.
|
|
* move - run the action under breakpoint and remove the rest of
|
|
breakpoints (continue execution without stopping again at next
|
|
actions). Pid parameter is mandatory.
|
|
* show - print details about the current breakpoint for pid. Pid
|
|
parameter is mandatory.
|
|
* eval - eval a pseudo-variable and print the result in RPC Pid
|
|
parameter is mandatory.
|
|
* log - eval a pseudo-variable and print the result in SIP router
|
|
logs. Pid parameter is mandatory.
|
|
|
|
Examples for using with sercmd:
|
|
dbg.bp off
|
|
dbg.bp on
|
|
dbg.bp release
|
|
dbg.bp on 1234
|
|
dbg.bp eval 1234 $fu
|
|
dbg.bp move 1234
|
|
|
|
6. Usage
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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'.
|
|
|
|
Here is an example of session:
|
|
...
|
|
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:test@kamailio.org
|
|
|
|
sercmd> dbg.bp move 6402
|
|
200 ok
|
|
...
|
|
|
|
Running the config trace looks like:
|
|
...
|
|
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_pro
|
|
cess_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_to
|
|
tag
|
|
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_met
|
|
hod
|
|
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=386 a=25 n=t_chec
|
|
k_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_met
|
|
hod
|
|
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_met
|
|
hod
|
|
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_met
|
|
hod
|
|
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_met
|
|
hod
|
|
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=isflag
|
|
set
|
|
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
|
|
...
|
|
|
|
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.
|