name mode size
..
doc 040000
Makefile 100644 211B
README 100644 13.01kB
debugger_act.c 100644 4.48kB
debugger_act.h 100644 1.02kB
debugger_api.c 100644 17.79kB
debugger_api.h 100644 1.11kB
debugger_mod.c 100644 4.16kB
README
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. 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. 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. 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. 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. 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. 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.