Troubleshooting the OpenSIPS routing logic

The brain of OpenSIPS is its script, holding the routing logic. And it order to reflect your custom routing logic – depending on the SIP service you implement -, the script is also a custom one. Meaning you need to build it.

As part of building a script, the troubleshooting is an important aspect. While you try to work out the routing logic in the script, you find yourself in the situation where OpenSIPS reacts (based on the script) in a different way than you intended.

So, how do you troubleshoot the OpenSIPS script? How do you understand how OpenSIPS is executing the routing script?

Stage 1: logging

As in any programming case, the simplest way to debug a script is by adding logs, logs that will give you an idea about the flow of execution in the script.

For this you can use the xlog() script statement. It gives you a rather decent control, by allowing you do set different logging levels (like debug, info, critical). And via xlog_level core parameter you can set a default verbosity, which may be changed during runtime via the xlog_level MI command.

Of course, the xlog’ing is a rudimentary and time consuming process, as you need to insert xlog() statements in different parts of your config, to try to track down the script execution.

Stage 2: script trace

As a more powerful alternative to the manual xlog’ing, OpenSIPS offers the script_trace()-ing capability. When enabled, OpenSIPS will automatically generate a log line for each step (function, assignment, test, etc) performed in the script, with its location (file and line number). So, you can get a complete tracing of the execution, step-by-step, of your script.

Even more, this tracing function allows you customize the logs, by adding your own formatted string, with desired variables. This is of a great help if you want to see how some variables do change during the script execution, like you monitor the value of the Request URI ($ru), to see where it gets modified across the script.

script_trace( 1, "$rm from $si, ruri=$ru", "dbg");

[line 578][dbg][module consume_credentials] -> (INVITE from 127.0.0.1 , ruri=sip:111211@opensips.org)
[line 581][dbg][core setbflag] -> (INVITE from 127.0.0.1 , ruri=sip:111211@opensips.org)
[line 583][dbg][assign equal] -> (INVITE from 127.0.0.1 , ruri=sip:111211@opensips.org)
[line 592][dbg][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
[line 585][dbg][module check_address] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
[line 589][dbg][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
[line 586][dbg][module is_method] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
[line 587][dbg][module trace_dialog] -> (INVITE 127.0.0.1 , ruri=sip:tester@opensips.org)
[line 590][dbg][core setflag] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org) 

This approach is:

• easy to use – only one function to use from script
• flexible – you may decide when to use it (scenario or user basis) and you customize the printed log
• powerful – you get the maximum amount of information, meaning the complete stepping on the script execution

Stage 3: tracer module

Taking one step further, besides knowing the flow of the execution in the script, you may also want to understand how this execution correlates with the SIP messaging performed by OpenSIPS.

We already know the tracer module, which is able to do SIP traffic capturing, to Homer, to log file or to opensips-cli console. But the tracer can do more than SIP, it can also capture the xlog() outputs from the script.

The trace() function may be instructed to capture both SIP and XLOG – see the third parameter, the type one.

trace($var(trace_id), "d", "sip|xlog", $var(user));

In this case, the tracing output will contain the in-sync mixture of SIP packages and xlog() lines. Which may be very helpful when looking to do time correlation between the SIP signaling and the script execution.

There are various ways to enhance the debugging technical, but these are the basic methods, able to solve the 95% of your issues.

To find more about OpenSIPS features, especially the ones from the upcoming 3.6 release, join us in Amsterdam for the OpenSIPS Summit 2025.