kamailio/modules_k/xlog

xlog Module

Elena-Ramona Modroiu

   rosdev.ro
   <ramona@rosdev.ro>

Edited by

Elena-Ramona Modroiu

   <ramona@rosdev.ro>

   Copyright © 2003 FhG FOKUS

   Copyright © 2008-2010 Elena-Ramona Modroiu
   Revision History
   Revision $Revision$ $Date$
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Implemented Specifiers
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Exported Parameters

              4.1. buf_size (integer)
              4.2. force_color (integer)
              4.3. long_format (integer)
              4.4. prefix (str)

        5. Exported Functions

              5.1. xlog([level,] format)
              5.2. xdbg(format)
              5.3. xlogl([level],format)
              5.4. xdbgl(format)

   List of Examples

   1.1. Set buf_size parameter
   1.2. Set force_color parameter
   1.3. Set long_format parameter
   1.4. Set prefix parameter
   1.5. xlog usage
   1.6. xdbg usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Implemented Specifiers
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Exported Parameters

        4.1. buf_size (integer)
        4.2. force_color (integer)
        4.3. long_format (integer)
        4.4. prefix (str)

   5. Exported Functions

        5.1. xlog([level,] format)
        5.2. xdbg(format)
        5.3. xlogl([level],format)
        5.4. xdbgl(format)

1. Overview

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

2. Implemented Specifiers

   In the xlog function, you use pseudo-variables, that are a part of
   Kamailio 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 Kamailio 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 Kamailio is available
   at: http://kamailio.org/dokuwiki/

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

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

3.2. External Libraries or Applications

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

4. Exported Parameters

   4.1. buf_size (integer)
   4.2. force_color (integer)
   4.3. long_format (integer)
   4.4. prefix (str)

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

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

4.3. long_format (integer)

   When set to 1, prints config file name in xlogl() and xdbgl() before
   line number.

   Default value is 0.

   Example 1.3. Set long_format parameter
...
modparam("xlog", "long_format", 1)
...

4.4. prefix (str)

   Prefix to be printed before the log message.

   Default value is "<script>: ".

   Example 1.4. Set prefix parameter
...
modparam("xlog", "prefix", "-xlog: ")
...

5. Exported Functions

   5.1. xlog([level,] format)
   5.2. xdbg(format)
   5.3. xlogl([level],format)
   5.4. xdbgl(format)

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 -5
          + L_BUG - log level -4
          + L_CRIT - log level -3
          + L_ERR - log level -1
          + L_WARN - log level 0
          + L_NOTICE - log level 1
          + L_INFO - log level 2
          + L_DBG - log level 3
          + $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 ANY_ROUTE.

   Example 1.5. 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");
...

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

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

5.3.  xlogl([level],format)

   Similar to xlog(), in addition is printing cfg line number at the
   beginning of message.

5.4.  xdbgl(format)

   Similar to xdbg(), in addition is printing cfg line number at the
   beginning of message.