Tracer 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.3.4. syslog_default_facility (string)
              1.3.5. syslog_default_level (integer)
              1.3.6. file_mode (integer)

        1.4. Exported Functions

              1.4.1. trace(trace_id, [scope], [type],
                      [trace_attrs], [flags], [correlation_id])

        1.5. Exported MI Functions

              1.5.1. trace
              1.5.2. trace_start
              1.5.3. trace_stop

        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. Set syslog_default_facility parameter
   1.5. Set syslog_default_level parameter
   1.6. Set file_mode parameter
   1.7. 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
   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.

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
     * b2b_logic - only if you want to trace B2B sessions.
     * dialog - only if you want to trace SIP dialogs (INVITE
       based).
     * tm - only if you want to trace SIP transactions.
     * proto_hep - only if you want to trace / replicate messages
       over HEP protocol.

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("tracer", "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("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")
...

1.3.3. trace_id (str)

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

   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 do
cs
 * 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")
...

1.3.4. syslog_default_facility (string)

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

   Default value is the value of syslog_facility.

   Example 1.4. Set syslog_default_facility parameter
...
modparam("tracer", "syslog_default_facility", "LOG_DAEMON")
...

1.3.5. syslog_default_level (integer)

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

   Default value is the value of log_level.

   Example 1.5. Set syslog_default_level parameter
...
modparam("tracer", "syslog_default_level", 2) # NOTICE
...

1.3.6. file_mode (integer)

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

   Example 1.6. Set file_mode parameter
...
modparam("tracer", "file_mode", 0644)
...

1.4. Exported Functions

1.4.1.  trace(trace_id, [scope], [type], [trace_attrs], [flags],
[correlation_id])

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

   Store or replicate 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:
     * 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, B2B session 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
          + 'b'/'B' trace all the traffic related to the B2B
            session to be later created
     * 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, B2B session 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.
     * 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 onlt the SIP callee side;
       If both C and c flags are missing, tracing of both
       sides/legs is assumed.
       NOTE these flags are supported only by transactional and
       dialog tracing
     * correlation_id (string,pvar) a custom SIP correlation ID to
       be forced (normally the SIP Call-ID is used) to correlate
       this traffic (transaction, dialog) with other traffic.

   Example 1.7. 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(use
r));
                }
        }
...
/* 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 w
ww_challenge() */
                        www_challenge("", "auth");
                }
        }

1.5. Exported MI Functions

1.5.1.  trace

   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

1.5.2.  trace_start

   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 message
       The 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

1.5.3.  trace_stop

   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

1.6. Database setup

   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.

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. Bogdan-Andrei Iancu (@bogdan-iancu) 115 88 1319 876
   2. Ionut Ionita (@ionutrazvanionita) 107 52 2676 1887
   3. Razvan Crainea (@razvancrainea) 76 54 1665 453
   4. Daniel-Constantin Mierla (@miconda) 49 26 2215 191
   5. Liviu Chircu (@liviuchircu) 26 23 87 80
   6. Vlad Paiu (@vladpaiu) 24 10 402 568
   7. Vlad Patrascu (@rvlad-patrascu) 17 8 286 335
   8. Henning Westerholt (@henningw) 11 6 146 155
   9. Andrei Datcu (@andrei-datcu) 11 5 284 135
   10. Alexandr Dubovikov (@adubovikov) 7 1 500 4

   All remaining contributors: Maksym Sobolyev (@sobomax), Dan
   Pascu (@danpascu), Ovidiu Sas (@ovidiusas), Walter Doekes
   (@wdoekes), Peter Lemenkov (@lemenkov), Dusan Klinec (@ph4r05),
   Zero King (@l2dy), Andreas Heise, Nick Altmann (@nikbyte),
   Sergio Gutierrez, okhowang, Konstantin Bokarius, 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 - Jul 2024
   2.  Razvan Crainea (@razvancrainea)     Jun 2011 - Jul 2024
   3.  Liviu Chircu (@liviuchircu)         Jan 2013 - May 2024
   4.  Ovidiu Sas (@ovidiusas)             Mar 2020 - Apr 2024
   5.  Vlad Paiu (@vladpaiu)               Jun 2011 - Dec 2023
   6.  Maksym Sobolyev (@sobomax)          Feb 2023 - Nov 2023
   7.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - May 2023
   8.  okhowang                            Mar 2023 - Mar 2023
   9.  Peter Lemenkov (@lemenkov)          Jun 2018 - Sep 2022
   10. Nick Altmann (@nikbyte)             Feb 2022 - Feb 2022

   All remaining contributors: Walter Doekes (@wdoekes), Zero King
   (@l2dy), Dan Pascu (@danpascu), Eric Tamme (@etamme), Ionut
   Ionita (@ionutrazvanionita), Dusan Klinec (@ph4r05), Andrei
   Datcu (@andrei-datcu), 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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov
   (@lemenkov), Nick Altmann (@nikbyte), Razvan Crainea
   (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), Liviu
   Chircu (@liviuchircu), Ovidiu Sas (@ovidiusas), Ionut Ionita
   (@ionutrazvanionita), Andrei Datcu (@andrei-datcu), 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
