Table of Contents
List of Tables
List of Examples
Offer a possibility to store incoming/outgoing SIP messages in database. Since version 2.2, proto_hep module needs to be loaded in order to duplicate with hep. All hep parameters moved inside proto_hep.
The 2.2 version of OpenSIPS came with a major improvement in tracer module. Now all you have to do is call trace() function with the proper parameters and it will do the job for you. Now you can trace messages, transactions and dialogs with the same function. Also, you can trace to multiple databases, multiple hep destinations and sip destinations using only one parameter. All you need now is defining trace_id parameters in modparam section and switch between them in tracer function. Also you cand turn tracing on and off using trace_on either globally(for all trace_ids) or for a certain trace_id.
IMPORTANT: In 2.2 version support for stateless trace has been removed.
The tracing tracing can be turned on/off using fifo command.
opensips-cli -x mi trace on opensips-cli -x mi trace [some_trace_id] on
opensips-cli -x mi trace off opensips-cli -x mi trace [some_trace_id] off
Starting with OpenSIPS 3.0 you can use the trace_start to create dynamic dynamic tracing destinations based on some custom filters.
The following modules must be loaded before this module:
database module - mysql, postrgress, dbtext, unixodbc... only if you are using a database type trace id
dialog - only if you want to trace dialogs.
tm - only if you want to trace dialogs/transactions.
proto_hep - only if you want to replicate messages over hep.
Parameter to enable/disable trace (on(1)/off(0))
Default value is "1"(enabled).
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".
Example 1.2. Set trace_local_ip parameter
...
#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, sip uri 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.
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.
Example 1.3. Set trace_id parameter
...
/*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 */
...
This function has replaced the sip_trace() in OpenSIPS 3.0.
Store or replocate current processed SIP message,transaction or dialogin database. 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:
trace_id (string) the name of the trace_id specifying where to do the tracing.
scope (string, optional) what do you want to trace: dialog, transaction or only the message. If not specified, will try the topmost trace that can be done: if dialog module loaded will trace dialogs, else if tm module loaded will trace transaction and if none of these loaded will trace messages.
Types can be the following:
'm'/'M' trace messages. Is the only one you should use in stateless mode.
't'/'T' trace transactions. If tm module not loaded, it will be in stateless transaction aware mode meaning that will catch selected requests both in and out and internally generated replies.
'd'/'D' trace dialog
type (string, optional) list of types of messages to be traced by this function; if not set only sip messages shall be traced; if the parameter is set, but sip is not specified, sip shall not be traced; all the parameters from the list shall be separated by '|'
Current possible types to be traced are the following:
sip - enable sip messages tracing;
xlog - enable xlog messages tracing in current scope(dialog, transaction or message);
rest - enable rest messages tracing;
trace_attrs (string, optional) this parameter replaces the traced_user_avp from the old version. To avoid duplicating an entry only for this parameter, whatever you put here(string/pvar) shall be stored in the trace_attrs column in the sip_trace table.
Example 1.4. trace() usage
...
/* 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("", 1);
}
}
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:
id (optional) - the name of the tracing instance. If this parameter is missing the command will either dump info for all tace ids(and return the global tracing state) or set the global tracing state.
mode (optional) - possible values are:
"on" - enable tracing
"off" - disable tracing
If the first parameter is missing, the command wil set the global tracing state, otherwise it will set the state for a specific trace id. If you turn global trace on but some of the trace ids had tracing set to off, then they shall not do tracing. If you want to turn the tracing on for all trace ids you will have to set it separately for each of them.
If this parameter is missing but the first is set, the command will only dump info about that specific trace id. If both parameters are missing, the command will return the global tracing state and dump info for each id.
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:
id - the name of the tracing instance.
uri - the destination uri for this instance.
filter (optional) - used to filter the traffic received by the sender. This parameter should be an array that can contain multiple filters in the condition=value format. Possible values for the condition argument are:
caller
- filter based on the caller (From username)callee
- filter based on the callee (R-URI username)ip
- filter based on the source IP of the messageThe condition parameter can consist of multiple different filters. In order to satisfy the overall condition and send traffic to the desired destination, all conditions have to be satisfied.
If this parameter is missing all traffic is forwarded to the destination.
The filter is applied for any incoming request
scope - the scope to engage the tracing for. The format received by this parameter is similar to the one received by the trace() function.
type - the type of messages you want to receive. The format received by this parameter is similar to the one received by the trace() function.
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:
id - the name of the tracing instance to be stopped.
MI FIFO Command to stop tracing calls from user Alice to user Bob:
opensips-cli -x mi trace_stop alice_bob
Before running OpenSIPS with tracer, you have to setup the database tables where the module will store the data. For that, if the table were not created by the installation script or you choose to install everything by yourself you can use the tracer-create.sql SQL script in the database directories in the opensips/scripts folder as template. You can also find the complete database documentation on the project webpage, https://opensips.org/docs/db/db-schema-devel.html.
ACKs related to a transaction that are leaving OpenSIPS are not traced since they are handled statelessly using forward_request function. Fixing it would mean to register a fwdcb callback that would be called for all the messages but would be used only by ACKs, which would be highly ineffective.
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Ionut Ionita (@ionutrazvanionita) | 107 | 52 | 2676 | 1887 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | 97 | 76 | 885 | 744 |
| 3. | Razvan Crainea (@razvancrainea) | 53 | 36 | 1246 | 368 |
| 4. | Daniel-Constantin Mierla (@miconda) | 48 | 26 | 2215 | 191 |
| 5. | Liviu Chircu (@liviuchircu) | 23 | 20 | 84 | 75 |
| 6. | Vlad Paiu (@vladpaiu) | 21 | 8 | 335 | 528 |
| 7. | Vlad Patrascu (@rvlad-patrascu) | 16 | 7 | 284 | 333 |
| 8. | Henning Westerholt (@henningw) | 11 | 6 | 146 | 155 |
| 9. | Andrei Datcu (@andrei-datcu) | 11 | 5 | 284 | 135 |
| 10. | Dan Pascu (@danpascu) | 6 | 4 | 18 | 11 |
All remaining contributors: Alexandr Dubovikov (@adubovikov), Dusan Klinec (@ph4r05), Andreas Heise, Sergio Gutierrez, Bogdan Iancu, Ovidiu Sas (@ovidiusas), Walter Doekes (@wdoekes), Konstantin Bokarius, Iouri Kharon, Peter Lemenkov (@lemenkov), Zero King (@l2dy), Edson Gellert Schubert, Elena-Ramona Modroiu, Eric Tamme (@etamme).
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Razvan Crainea (@razvancrainea) | Jun 2011 - Oct 2020 |
| 2. | Liviu Chircu (@liviuchircu) | Jan 2013 - Jul 2020 |
| 3. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jul 2006 - Jun 2020 |
| 4. | Ovidiu Sas (@ovidiusas) | Mar 2020 - Mar 2020 |
| 5. | Zero King (@l2dy) | Mar 2020 - Mar 2020 |
| 6. | Dan Pascu (@danpascu) | Nov 2008 - May 2019 |
| 7. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Apr 2019 |
| 8. | Walter Doekes (@wdoekes) | Apr 2019 - Apr 2019 |
| 9. | Bogdan Iancu | Apr 2019 - Apr 2019 |
| 10. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
All remaining contributors: Eric Tamme (@etamme), Ionut Ionita (@ionutrazvanionita), Dusan Klinec (@ph4r05), Andrei Datcu (@andrei-datcu), Vlad Paiu (@vladpaiu), Alexandr Dubovikov (@adubovikov), Sergio Gutierrez, Daniel-Constantin Mierla (@miconda), Iouri Kharon, Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw), Andreas Heise, Elena-Ramona Modroiu.
(1) including any documentation-related commits, excluding merge commits
Last edited by: Ovidiu Sas (@ovidiusas), Vlad Patrascu (@rvlad-patrascu), Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea), Peter Lemenkov (@lemenkov), Ionut Ionita (@ionutrazvanionita), Andrei Datcu (@andrei-datcu), Bogdan-Andrei Iancu (@bogdan-iancu), Alexandr Dubovikov (@adubovikov), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw), Elena-Ramona Modroiu.
Documentation Copyrights:
Copyright © 2006 Voice Sistem SRL