Tips & Tricks for Advanced SIP Capturing

Doing call tracing with Homer became really simple and straight forward with OpenSIPS 2.3 .

Just one line of config file and you can capture your SIP traffic (and even more) per message, transaction or dialog bases.

Following the OpenSIPS 3.1 release which was focused on complex call crafting (Class 5 features oriented), we felt the need of having more complex tracing capabilities ( for a more refined control over the tracing at script level), to match the complexity of the Class 5 calling scenarios.

So, OpenSIPS 3.2, the next LTS in line at this date, brings a more refined control over the tracing in OpenSIPS, some good to know Tips and Tricks :).

Extra Call Correlation

By default, SIPCapture / Homer is doing per call correlation – it correlates only the SIP messages with the same Call-ID, so belonging to the same SIP dialog.

But there are case where multiple SIP calls should be seen / charted together in Homer, just because they are part of a single, more complex SIP action. Examples are many:

• Call Pickup – the original incoming call (to be picked) and the call doing the actual pickup;
• Call Parking – the original call, the parked call, the retrieved call;
• Call Transfer – the initial call and the transferred call;
• Call Queuing – the inbound call, the calls going to media server (playback) and the outbound call to the agent.
• SIP B2B – the two SIP calls on the sides of the B2B
• Call looping – looping a call via an external Media Server that acts as a B2B

To get the best out of tracing (and make an easier life for our DevOps colleagues ), all the calls belonging to the same scenario should be charted / shown together – they must be correlated between them.

With OpenSIPS 3.2, the trace() function accepts an options parameter for providing a extra correlation ID for that call. The idea is to use the same extra correlation ID for all the calls belonging to the same scenario. What should be the value of this correlation ID? Any kind of string – for example it can be the SIP Call-Id of the the first call in the scenario or it can be an UUID generated via the uuid() function.

Here is a short example of how to correlate the two calls involved in an attended transfer scenario. Assuming you do dialog based capturing, normally you have something like this when handling the initial requests.

if (is_method("INVITE")) {
	trace( "hid", "d", "sip");
}

To correlate the call resulting from the transfer, let’s use as correlation ID the SIP Call-Id of the initial call:

if (is_method("INVITE")) {
	if (is_present_hf("Replaces")) {
		## this is a call resulted from an attended transfer
		$var(callid) = $(hdr(Replaces){s.select,0,;});
		trace( "hid", "d", "sip", , , "$var(callid)");
                ## this is the extra correlation ID ^^^^^
	} else {
		trace( "hid", "d", "sip");
	}
}

As a result of this correlation, in Homer, you will both calls, the original one and the transferred one, as a single diagram / flow.

Partial Call Capturing

Another need addressed by the OpenSIPS 3.2 is related to doing tracing in a chain of SIP servers.

The SIP platforms are complex, potentially consisting of multiple OpenSIPS instances. Like one OpenSIPS acting as SBC, another one as Main Proxy, one as Presence Server or another hosting a Call Queuing.

If we enable regular tracing (of all incoming and outgoing SIP message) on each OpenSIPS component, we will get duplicated capturing for the traffic going between two OpenSIPS instances.

Assuming a call from an end user, going via OpenSIPS SBC, to the OpenSIPS Main Proxy and finally to a Carrier, with full tracing, the traffic between OpenSIPS SBC and OpenSIPS Main Proxy will be captured twice, by both OpenSIPS instances.

To solve this problem, OpenSIPS 3.2 allows partial tracing – the ability to trace only the traffic from caller or callee side. This is done via the new control flags that are available in the trace() function.

"flags" (string,pvar) are some control flags over the tracing process (how and what to be traced).

    C - trace only the SIP caller side;

    c - trace only the SIP callee side;

If both C and c flags are missing, tracing of both sides/legs is assumed.

A generic approach will be configure OpenSIPS to skip the “caller” side tracing if the call comes from another OpenSIPS in the platform. And only the first OpenSIPS in the chain will do full tracing.

if (is_method("INVITE")) {
	if ($si=="1.2.3.4" || check_source_address("1")) {
		## call within the platform
		trace( "hid", "d", "sip", , "c");
	} else {
		## do full tracing, both caller and callee
		trace( "hid", "d", "sip");
	}
}

These flags make sense only when doing transactional or dialog based SIP tracing.

B2B Call Capturing

With OpenSPIS 3.2 , the SIP capturing in B2B scenarios became simpler, mainly because the B2B support in OpenSIPS became simpler.

The new B2B engine is script driven, so much easier to integrate at script level with other functionalities, like SIP capturing.

A first approach is to manually trace from script all the transactions belonging to the same B2B session and use the B2B logic key to correlate them all.

What you need to do is to hook the tracing trigger on top of the scripting routes where you “see” the B2B requests, so you can start transactional tracing for them. Such routes are the “local_route” for outbound requests and the “script_req_route” for the inbound requests.

modparam("b2b_logic", "script_req_route", "b2b_logic_request")

route {
    ...
    trace( "hid", "t", "sip", , , "$b2b_logic.key");
    b2b_init_request("prepaid");
    exit;
 }

 local_route {
    ## is this outbound request part of a B2B session?
    if ($b2b_logic.key!=NULL)
       trace( "hid", "t", "sip", , , "$b2b_logic.key");
 }

 route[b2b_logic_request] {
    ## this is an inbound request part of a B2B session
    trace( "hid", "t", "sip", , , "$b2b_logic.key");
 }

Of course, in order to do selective tracing (only for some B2B sessions), you can use a B2B context variable $b2b_logic.ctx to flag if that B2B sessions is to be traced or not.

Another alternative for B2B tracing is an automatic one, where you call the “trace” function only once – with the ‘b’ (b2b) tracing scope -, when the B2B session is created – this will automatically trace all the messages related to that B2B session.

route {
    ...
    trace( "hid", "b", "sip");
    b2b_init_request("preppaid");
    exit;
 }

Still this option is still under development. This is a first version of it, a pull request from Nick Altmann, one of the senior OpenSIPS contributors. This PR is still in reviewing mode, but it will definitely make its way into OpenSIPS 3.2 LTS.

Conclusions

The upcoming OpenSIPS 3.2 LTS has more to offer when comes to SIP tracing, addressing real needs of more complex OpenSIPS deployments – complex as SIP flows/scenarios, complex as multi-server architecture.