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 siptrace module. Now all you have to do is call sip_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 siptrace 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.
opensipsctl fifo sip_trace on opensipsctl fifo sip_trace [some_trace_id] on
opensipsctl fifo sip_trace off opensipsctl fifo sip_trace [some_trace_id] off
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("siptrace", "trace_local_ip", "10.1.1.1:5064")
...
...
#Resulting address: tcp:10.1.1.1:5060
modparam("siptrace, "trace_local_ip", "tcp:10.1.1.1")
...
...
#Resulting address: tcp:10.1.1.1:5064
modparam("siptrace", "trace_local_ip", "tcp:10.1.1.1:5064")
...
...
#Resulting address: udp:10.1.1.1:5060
modparam("siptrace", "trace_local_ip", "10.1.1.1")
...
Specify a destination for the trace. This can be a hep uri, sip uri or a database url and a table. All parameters inside trace_id must be separated by ;. 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 uris must be specified as hep:host:port.
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 sip_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. For HEP ids, if transport parameter is not set default will be TCP for version 3 and UDP for 1 and 2. Also if version not set, version 3 will be used by default.
Example 1.3. Set trace_id parameter
...
/*DB trace id*/
modparam("siptrace", "trace_id",
"[tid]
uri=mysql://xxxx:xxxx@10.10.10.10/opensips;
table=new_sip_trace;")
/*hep trace id*/
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.10:6161;")
/*sip trace id*/
modparam("siptrace", "trace_id",
"[tid]uri=sip:10.10.10.11:5060;")
/* notice that they all have the same name
* meaning that calling sip_trace("tid",...)
* will do sql, sip and hep tracing */
/* hep version 3 with tcp - ALSO DEFAULT ONE */
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.12:5061;transport=tcp;version=3;")
/* hep version 3 with udp (version not set-default will be 3)*/
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.12:5061;transport=udp;")
/* hep version 1 */
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.12:5061;version=1;")
...
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 sip_trace() function. Since version 2.2, sip_trace() 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, pvar) the name of the trace_id specifying where to do the tracing.
type (string) 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
trace_attrs (string,pvar) 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. sip_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 */
if (has_totag()) {
match_dialog();
} else {
if (is_method("INVITE") {
sip_trace("$var(trace_id)", "d", "$var(user)");
}
}
...
/* Example 2: how to trace initial INVITE and BYE */
if (has_totag()) {
if (is_method("BYE")) {
sip_trace("$var(trace_id)", "m", "$var(user)");
}
} else {
if (is_method("INVITE")) {
sip_trace("$var(trace_id)", "m", "$var(user)");
}
}
...
/* Example 3: trace initial INVITE transaction */
if (!has_totag()) {
if (is_method("INVITE")) {
sip_trace("$var(trace_id)", "t", "$var(user)");
}
}
...
/* Example 4: stateless transaction aware mode!*/
/* tm module must not be loaded */
if (is_method("REGISTER")) {
sip_trace("$var(trace_id)", "t", "$var(user)");
if (!www_authorize("", "subscriber")) {
/* siptrace will also catch the 401 generated by www_challenge() */
www_challenge("", "1");
}
}
Name: sip_trace
Parameters:
trace_id/trace_mode : if it is a trace_id name it dumps info about that trace id if the second parameter is not set to on/off or it turns tracing on/off for a certain trace id if it is set, else if it's on/off it turns on/off tracing for all the trace ids. If you turn global trace on but some of the trace ids had trace to off, then they shall not do tracing. In order to do that you have to set the trace_on parameter for each trace_id. Possible values are:
on
off
trace_id name
The parameter is optional - if missing, the command will return the status of the SIP message tracing (as string “on” or “off”) marked with global and the status for each trace id without changing anything.
trace_mode : this parameter has the same meaning as the trace_mode in the first parameter, but this time it enables/disables tracing for a certain trace id given in the first parameter.
MI FIFO Command Format:
:sip_trace:_reply_fifo_file_ trace_id/trace_mode trace_mode _empty_line_
Before running OpenSIPS with siptrace, 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 siptrace-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, http://www.opensips.org/html/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. | Bogdan-Andrei Iancu (@bogdan-iancu) | 76 | 60 | 650 | 542 |
| 2. | Ionut Ionita (@ionutrazvanionita) | 65 | 24 | 1856 | 1420 |
| 3. | Daniel-Constantin Mierla (@miconda) | 48 | 26 | 2215 | 191 |
| 4. | Vlad Paiu (@vladpaiu) | 21 | 8 | 335 | 528 |
| 5. | Razvan Crainea (@razvancrainea) | 19 | 16 | 124 | 85 |
| 6. | Liviu Chircu (@liviuchircu) | 14 | 12 | 61 | 46 |
| 7. | Henning Westerholt (@henningw) | 11 | 6 | 146 | 155 |
| 8. | Andrei Datcu (@andrei-datcu) | 11 | 5 | 284 | 135 |
| 9. | Alexandr Dubovikov (@adubovikov) | 6 | 1 | 500 | 4 |
| 10. | Dusan Klinec | 4 | 2 | 8 | 4 |
All remaining contributors: Andreas Heise, Sergio Gutierrez, Vlad Patrascu (@rvlad-patrascu), Dan Pascu (@danpascu), Konstantin Bokarius, Iouri Kharon, Edson Gellert Schubert, Elena-Ramona Modroiu, Stephane Alnet.
(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. | Liviu Chircu (@liviuchircu) | Jan 2013 - Oct 2018 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jul 2006 - Jun 2018 |
| 3. | Razvan Crainea (@razvancrainea) | Jun 2011 - Sep 2017 |
| 4. | Vlad Patrascu (@rvlad-patrascu) | Aug 2017 - Aug 2017 |
| 5. | Ionut Ionita (@ionutrazvanionita) | Nov 2014 - Feb 2017 |
| 6. | Stephane Alnet | Nov 2016 - Nov 2016 |
| 7. | Dusan Klinec | Dec 2015 - Dec 2015 |
| 8. | Andrei Datcu (@andrei-datcu) | Jun 2014 - Jul 2014 |
| 9. | Vlad Paiu (@vladpaiu) | Jun 2011 - Nov 2013 |
| 10. | Alexandr Dubovikov (@adubovikov) | Nov 2011 - Nov 2011 |
All remaining contributors: Sergio Gutierrez, Dan Pascu (@danpascu), 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: Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Ionut Ionita (@ionutrazvanionita), Andrei Datcu (@andrei-datcu), Razvan Crainea (@razvancrainea), Alexandr Dubovikov (@adubovikov), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw), Elena-Ramona Modroiu.
doc copyrights:
Copyright © 2006 Voice Sistem SRL