SipTrace Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. trace_on (integer)
              1.3.2. trace_local_ip (str)
              1.3.3. trace_id (str)

        1.4. Exported Functions

              1.4.1. sip_trace(trace_id, [scope, [type,
                      [trace_attrs]]])

        1.5. Exported MI Functions

              1.5.1. sip_trace

        1.6. Database setup
        1.7. Known issues

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set trace_on parameter
   1.2. Set trace_local_ip parameter
   1.3. Set trace_id parameter
   1.4. sip_trace() usage

Chapter 1. Admin Guide

1.1. Overview

   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

1.2. Dependencies

1.2.1. OpenSIPS Modules

   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.

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.3.1. trace_on (integer)

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

   Default value is "1"(enabled).

   Example 1.1. Set trace_on parameter
...
modparam("siptrace", "trace_on", 1)
...

1.3.2. trace_local_ip (str)

   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")
...

1.3.3. trace_id (str)

   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 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.

   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 with the hep id defined in proto_hep; check proto_hep do
cs
 * for more information */
modparam("proto_hep", "hep_id",  "[hid]10.10.10.10")
modparam("siptrace", "trace_id", "[tid]uri=hep:hid")
/*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 */
...

1.4. Exported Functions

1.4.1.  sip_trace(trace_id, [scope, [type, [trace_attrs]]])

   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.
     * scope (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
     * type (string) 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,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 sip and xlog */
        if (has_totag()) {
                match_dialog();
        } else {
                if (is_method("INVITE") {
                        sip_trace("$var(trace_id)", "d", "sip|xlog", "$v
ar(user)");
                }
        }
...
/* Example 2: how to trace initial INVITE and BYE, sip and rest */
        if (has_totag()) {
                if (is_method("BYE")) {
                        sip_trace("$var(trace_id)", "m", "sip|rest", "$v
ar(user)");
                }
        } else {
                if (is_method("INVITE")) {
                        sip_trace("$var(trace_id)", "m", "sip|rest", "$v
ar(user)");
                }
        }

...
/* Example 3: trace initial INVITE transaction's only xlog and rest, no
sip */
        if (!has_totag()) {
                if (is_method("INVITE")) {
                        sip_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")) {
                sip_trace("$var(trace_id)", "t", "xlog|rest", "$var(user
)");
                if (!www_authorize("", "subscriber")) {
                        /* siptrace will also catch the 401 generated by
 www_challenge() */
                        www_challenge("", "1");
                }
        }

1.5. Exported MI Functions

1.5.1.  sip_trace

   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_

1.6. Database setup

   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,
   https://opensips.org/docs/db/db-schema-devel.html.

1.7. Known issues

   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.

Chapter 2. Contributors

2.1. By Commit Statistics

   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) 96 75 876 740
   3. Daniel-Constantin Mierla (@miconda) 48 26 2215 191
   4. Razvan Crainea (@razvancrainea) 26 22 129 88
   5. Vlad Paiu (@vladpaiu) 21 8 335 528
   6. Liviu Chircu (@liviuchircu) 20 17 74 72
   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. Vlad Patrascu (@rvlad-patrascu) 4 2 31 30

   All remaining contributors: Dusan Klinec (@ph4r05), Andreas
   Heise, Sergio Gutierrez, Dan Pascu (@danpascu), Konstantin
   Bokarius, Walter Doekes (@wdoekes), Iouri Kharon, 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

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2006 - Jun 2020
   2.  Razvan Crainea (@razvancrainea)     Jun 2011 - Sep 2019
   3.  Walter Doekes (@wdoekes)            Apr 2019 - Apr 2019
   4.  Liviu Chircu (@liviuchircu)         Jan 2013 - Oct 2018
   5.  Eric Tamme (@etamme)                Sep 2017 - Sep 2017
   6.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Aug 2017
   7.  Ionut Ionita (@ionutrazvanionita)   Nov 2014 - Apr 2017
   8.  Dusan Klinec (@ph4r05)              Dec 2015 - Dec 2015
   9.  Andrei Datcu (@andrei-datcu)        Jun 2014 - Jul 2014
   10. Vlad Paiu (@vladpaiu)               Jun 2011 - Nov 2013

   All remaining contributors: Alexandr Dubovikov (@adubovikov),
   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

Chapter 3. Documentation

3.1. Contributors

   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
