xlog Module

Elena-Ramona Modroiu

   rosdev.ro
   <ramona@rosdev.ro>

Edited by

Elena-Ramona Modroiu

   <ramona@rosdev.ro>

   Copyright © 2003 FhG FOKUS

   Copyright © 2005 voice-system.ro

   Copyright © 2008 Elena-Ramona Modroiu
   Revision History
   Revision $Revision: 5906 $ $Date: 2009-07-21 10:45:05 +0300
                              (Tue, 21 Jul 2009) $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Implemented Specifiers
        1.3. Dependencies

              1.3.1. OpenSIPS Modules
              1.3.2. External Libraries or Applications

        1.4. Exported Parameters

              1.4.1. buf_size (integer)
              1.4.2. force_color (integer)

        1.5. Exported Functions

              1.5.1. xlog([level,] format)
              1.5.2. xdbg(format)

   List of Examples

   1.1. Set buf_size parameter
   1.2. Set force_color parameter
   1.3. xlog usage
   1.4. xdbg usage

Chapter 1. Admin Guide

1.1. Overview

   This module provides the possibility to print user formatted
   log or debug messages from OpenSIPS scripts, similar to printf
   function. A C-style printf specifier is replaced with a part of
   the SIP request or other variables from system. Section 1.2,
   "Implemented Specifiers" shows what can be printed out.

1.2. Implemented Specifiers

   In the xlog function, you use pseudo-variables, that are a part
   of OpenSIPS core and are used by other modules as well (e.g.,
   avpops in the function avp_printf())

   The most important changes from earlier versions of OpenSIPS
   are:
     * - '%' has been replaced by '$'
     * - to print a header, use now $hdr(header_name[index])
       instead of %{header_name[index]}
     * - to print an AVP, use now $avp([si]:avp_id[index]) instead
       of %{[si]:avp_id[index]} or $avp([$avp_alias[index])
       instead of %{[$avp_alias[index]}

   The full list of available pseudo-variables in OpenSIPS is
   availabe at: http://opensips.org/dokuwiki/

1.3. Dependencies

1.3.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * No dependencies on other OpenSIPS modules.

1.3.2. External Libraries or Applications

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

1.4. Exported Parameters

1.4.1. buf_size (integer)

   Maximum size of the log message.

   Default value is 4096.

   Example 1.1. Set buf_size parameter
...
modparam("xlog", "buf_size", 8192)
...

1.4.2. force_color (integer)

   When set to 1, forces color printing even if log_stderror=0.

   Default value is 0.

   Example 1.2. Set force_color parameter
...
modparam("xlog", "force_color", 0)
...

1.5. Exported Functions

1.5.1.  xlog([level,] format)

   Print a formated message using LOG function.

   Meaning of the parameters are as follows:
     * level - The level that will be used in LOG function. It can
       be:
          + L_ALERT - log level -3
          + L_CRIT - log level -2
          + L_ERR - log level -1
          + L_WARN - log level 1
          + L_NOTICE - log level 2
          + L_INFO - log level 3
          + L_DBG - log level 4
          + $pv - any valid pseudo-variable, that has an integer
            value. See above options for valid log levels.
       If it is not a pseudo-variable, then what really matters is
       the third letter of the value. If the log level is higher
       than the "debug" global parameter, the message is not
       printed to syslog.
       If this parameter is missing, the implicit log level is
       'L_ERR'.
     * format - The formatted string to be printed.

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

   Example 1.3. xlog usage
...
xlog("L_ERR", "time [$Tf] method ($rm) r-uri ($ru) 2nd via ($hdr(via[1])
)\n");
...
xlog("time [$Tf] method ($rm) r-uri ($ru) 2nd via ($hdr(via[1]))\n");
...
$var(loglevel) = 2;
xlog("$var(loglevel)", "time [$Tf] method ($rm) r-uri ($ru)\n");
...

1.5.2.  xdbg(format)

   Print a formatted message using DBG function.

   Meaning of the parameters is as follows:
     * format - The formatted string to be printed.

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

   Example 1.4. xdbg usage
...
xdbg("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
...