Tracer Module

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

Parameter to enable/disable trace (on(1)/off(0))

Default value is "1"(enabled).

...
modparam("tracer", "trace_on", 1)
...

The address to be used in the fields that specify the source address (protocol, ip and port) for locally generated messages. If not set, the module sets it to the address of the socket that will be used to send the message. Protocol and/or port are optional and if omitted will take the default values: udp and 5060.

Default value is "NULL".

...
#Resulting address: udp:10.1.1.1:5064
modparam("tracer", "trace_local_ip", "10.1.1.1:5064")
...

...
#Resulting address: tcp:10.1.1.1:5060
modparam("tracer, "trace_local_ip", "tcp:10.1.1.1")
...

...
#Resulting address: tcp:10.1.1.1:5064
modparam("tracer", "trace_local_ip", "tcp:10.1.1.1:5064")
...

...
#Resulting address: udp:10.1.1.1:5060
modparam("tracer", "trace_local_ip", "10.1.1.1")
...

Specify a destination for the trace. This can be a hep id defined in proto_hep, a sip uri, a file, a syslog facility or a database url and a table. All parameters inside trace_id must be separated by ;, excepting the last one. The parameters are given in key-value format, the possible keys being uri for HEP and SIP IDs and uri and table for databases. The format is [id_name]key1=value1;key2=value2;. HEP id's MUST be defined in proto_hep in order to be able to use them here.

When the uri is a file, the path to the file has to be specified after the colon. The output is always appended if the file exists, or created if it doesn't, using file_mode permissions.

When the uri is syslog, it has to follow the following format: syslog[:FACILITY[:LEVEL]]. The default facility and levels are the ones used by OpenSIPS (log_facility and log_level). These can be tuned using syslog_default_facility and syslog_default_level parameters.

One can declare multiple types of tracing under the same trace id, being identified by their name. So if you define two database url, one hep uri and one sip uri with the same name, when calling trace() with this name tracing shall be done to all the destinations.

All the old parameter such as db_url, table and duplicate_uri will form the trace id with the name "default".

No default value. If not set the module will be useless.

...
/*DB trace id*/
modparam("tracer", "trace_id",
"[tid]
uri=mysql://xxxx:xxxx@10.10.10.10/opensips;
table=new_sip_trace;")
/* hep trace id with the hep id defined in proto_hep; check proto_hep docs
 * for more information */
modparam("proto_hep", "hep_id",  "[hid]10.10.10.10")
modparam("tracer", "trace_id", "[tid]uri=hep:hid")
/*sip trace id*/
modparam("tracer", "trace_id",
"[tid]uri=sip:10.10.10.11:5060")
/* notice that they all have the same name
 * meaning that calling trace("tid",...)
 * will do sql, sip and hep tracing */
/*file trace id*/
modparam("tracer", "trace_id",
"[tid]uri=file:/path/to/file")
/*syslog trace id at error (level -1)*/
modparam("tracer", "trace_id",
"[tid]uri=syslog:local0:-1")
...

When syslog tracing is used, this parameter specifies the log facility to write traces to.

Default value is the value of log_facility.

...
modparam("tracer", "syslog_default_facility", "LOG_DAEMON")
...

When syslog tracing is used, this parameter specifies the level to write traces to.

Default value is the value of log_level.

...
modparam("tracer", "syslog_default_level", 2) # NOTICE
...

When file tracing is used, this parameter specifies the permissions to be used to create the trace files. It follows the UNIX conventions.

Default value is 0600 (rw-------).

...
modparam("tracer", "file_mode", 0644)
...

This function has replaced the sip_trace() in OpenSIPS 3.0.

Store or replocate current processed SIP message, transaction / dialog or B2B session. It is stored in the form prior applying chages made to it. The traced_user_avp parameter is now an argument to trace() function. Since version 2.2, this function also catches internally generated replies in stateless mode(sl_send_reply(...)).

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.

Meaning of the parameters is as follows:

...
/* see declaration of tid in trace_id section */
	$var(trace_id) = "tid";
	$var(user) = "osip_user@opensips.org";

...
/* Example 1: how to trace a dialog sip and xlog */
	if (has_totag()) {
		match_dialog();
	} else {
		if (is_method("INVITE") {
			trace($var(trace_id), "d", "sip|xlog", $var(user));
		}
	}
...
/* Example 2: how to trace initial INVITE and BYE, sip and rest */
	if (has_totag()) {
		if (is_method("BYE")) {
			trace($var(trace_id), "m", "sip|rest", $var(user));
		}
	} else {
		if (is_method("INVITE")) {
			trace($var(trace_id), "m", "sip|rest", $var(user));
		}
	}

...
/* Example 3: trace initial INVITE transaction's only xlog and rest, no sip */
	if (!has_totag()) {
		if (is_method("INVITE")) {
			trace($var(trace_id), "t", "xlog|rest", $var(user));
		}
	}
...
/* Example 4: stateless transaction aware mode!*/
/* tm module must not be loaded */
	if (is_method("REGISTER")) {
		trace($var(trace_id), "t", "xlog|rest", $var(user));
		if (!www_authorize("", "subscriber")) {
			/* tracer will also catch the 401 generated by www_challenge() */
			www_challenge("", "auth");
		}
	}

Enable/disable tracing(globally or for a specific trace id) or dump info about trace ids. This command requires named parameters (each parameter is ginven in the format param_name=param_value).

Name: trace

Parameters:

MI FIFO Command Format:

# Display global tracing mode and all trace destinations:
opensips-cli -x mi trace
# Turn off global tracing:
opensips-cli -x mi trace mode=off
# Turn on tracing for destination id tid2:
opensips-cli -x mi trace id=tid2 mode=on
		

Creates a dynamic tracing destination based using custom filters. This function can be used to debug calls for certain destinations real-time.

Dynamic destinations are not restart persistent!

Name: trace_start

Parameters:

MI FIFO Command to start tracing calls from IP 127.0.0.1 to HEP destination 10.0.0.1:9060:

		opensips-cli -x mi trace_start id=ip_filter uri=hep:10.0.0.1:9060 filter=ip=127.0.0.1
		

MI FIFO Command to start tracing calls from user Alice to user Bob:

		opensips-cli -x mi trace_start id=alice_bob uri=hep:10.0.0.1:9060 filter=caller=Alice filter=caller=Bob
		

Stops OpenSIPS from sending traffic to a dynamic trace id created using the trace_start command.

Name: trace_stop

Parameters:

MI FIFO Command to stop tracing calls from user Alice to user Bob:

		opensips-cli -x mi trace_stop alice_bob