# &adminguide;

## 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. shows what can be printed out.

## 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/wiki/

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- No dependencies on other &kamailio; modules.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None.

## Parameters

### `buf_size` (integer)

Maximum size of the log message.

Default value is 4096.

#### Set `buf_size` parameter

    ...
    modparam("xlog", "buf_size", 8192)
    ...

### `force_color` (integer)

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

Default value is 0.

#### Set `force_color` parameter

    ...
    modparam("xlog", "force_color", 0)
    ...

### `long_format` (integer)

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

Default value is 0.

#### Set `long_format` parameter

    ...
    modparam("xlog", "long_format", 1)
    ...

### `prefix` (str)

Prefix to be printed before the log message.

Default value is "<script>: ".

#### Set `prefix` parameter

    ...
    modparam("xlog", "prefix", "-xlog: ")
    ...

### `log_facility` (string)

Syslog facility to be used when printing xlog messages. In this way you can get the xlog messages in a separate syslog file than the debug messages issued from source code.

Default value is NULL (unset - use same facility as source code debug messages).

#### log_facility example

    modparam("xlog", "log_facility", "LOG_DAEMON")

### `log_colors` (string)

Update terminal colors used by core for log levels (when log_stderr=1 and log_color=1). The value has to be 'logname=colors', where colors is two characters specifying foreground and background in the same format as $C(xy) variable.

The parameter can be set many times, its value can also be a ';'-separated list of color specs.

Default value is NULL.

#### log_colors example

    modparam("xlog", "log_colors", "L_ERR=cr")
    modparam("xlog", "log_colors", "L_ERR=cr;L_WARN=px")

## Functions

### `xlog([ [facility,] level,] format)`

Print a formated message using LOG function.

Meaning of the parameters are as follows:

- facility - The log facility that will be used for this single log message.

  If this parameter is missing, the implicit facility is either the facility set with the 'log_facility' module parameter or the core's log facility.

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

#### `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");
    ...
    xlog("LOG_LOCAL3", "L_ERR", "this message will be sent to syslog facility LOG_LOCAL3\n");
    ...

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

#### `xdbg` usage

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

### `xlogl([ [facility,] level,] format)`

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

### `xdbgl(format)`

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