16361de462b9a3ed816389d452d369a470d8073a
[sip-router] / src / modules / xlog / README
1 xlog Module
2
3 Elena-Ramona Modroiu
4
5    rosdev.ro
6    <ramona@rosdev.ro>
7
8 Edited by
9
10 Elena-Ramona Modroiu
11
12    <ramona@rosdev.ro>
13
14    Copyright © 2003 FhG FOKUS
15
16    Copyright © 2008-2010 Elena-Ramona Modroiu
17      __________________________________________________________________
18
19    Table of Contents
20
21    1. Admin Guide
22
23         1. Overview
24         2. Implemented Specifiers
25         3. Dependencies
26
27               3.1. Kamailio Modules
28               3.2. External Libraries or Applications
29
30         4. Parameters
31
32               4.1. buf_size (integer)
33               4.2. force_color (integer)
34               4.3. long_format (integer)
35               4.4. prefix (str)
36               4.5. log_facility (string)
37               4.6. log_colors (string)
38               4.7. methods_filter (int)
39
40         5. Functions
41
42               5.1. xlog([ [facility,] level,] format)
43               5.2. xdbg(format)
44               5.3. xinfo(format)
45               5.4. xnotice(format)
46               5.5. xwarn(format)
47               5.6. xerr(format)
48               5.7. xbug(format)
49               5.8. xcrit(format)
50               5.9. xalert(format)
51               5.10. xlogl([ [facility,] level,] format)
52               5.11. xdbgl(format)
53               5.12. xlogm(level, format)
54
55    List of Examples
56
57    1.1. Set buf_size parameter
58    1.2. Set force_color parameter
59    1.3. Set long_format parameter
60    1.4. Set prefix parameter
61    1.5. log_facility example
62    1.6. log_colors example
63    1.7. Set methods_filter parameter
64    1.8. xlog usage
65    1.9. xdbg usage
66    1.10. xinfo usage
67    1.11. xnotice usage
68    1.12. xwarn usage
69    1.13. xerr usage
70    1.14. xbug usage
71    1.15. xcrit usage
72    1.16. xalert usage
73
74 Chapter 1. Admin Guide
75
76    Table of Contents
77
78    1. Overview
79    2. Implemented Specifiers
80    3. Dependencies
81
82         3.1. Kamailio Modules
83         3.2. External Libraries or Applications
84
85    4. Parameters
86
87         4.1. buf_size (integer)
88         4.2. force_color (integer)
89         4.3. long_format (integer)
90         4.4. prefix (str)
91         4.5. log_facility (string)
92         4.6. log_colors (string)
93         4.7. methods_filter (int)
94
95    5. Functions
96
97         5.1. xlog([ [facility,] level,] format)
98         5.2. xdbg(format)
99         5.3. xinfo(format)
100         5.4. xnotice(format)
101         5.5. xwarn(format)
102         5.6. xerr(format)
103         5.7. xbug(format)
104         5.8. xcrit(format)
105         5.9. xalert(format)
106         5.10. xlogl([ [facility,] level,] format)
107         5.11. xdbgl(format)
108         5.12. xlogm(level, format)
109
110 1. Overview
111
112    This module provides the possibility to print user formatted log or
113    debug messages from Kamailio scripts, similar to the printf function. A
114    C-style printf specifier is replaced with a part of the SIP request or
115    other variables from system.
116
117 2. Implemented Specifiers
118
119    In the xlog function, you use pseudo-variables, that are a part of
120    Kamailio core and are used by other modules as well (e.g., avpops in
121    the function avp_printf())
122
123    The most important changes from earlier versions of Kamailio are:
124      * - '%' has been replaced by '$'
125      * - to print a header, use $hdr(header_name[index]) instead of
126        %{header_name[index]}
127      * - to print an AVP, use now $avp([si]:avp_id[index]) instead of
128        %{[si]:avp_id[index]} or $avp([$avp_alias[index]) instead of
129        %{[$avp_alias[index]}
130
131    The full list of available pseudo-variables in Kamailio is available
132    at: http://kamailio.org/wiki/
133
134 3. Dependencies
135
136    3.1. Kamailio Modules
137    3.2. External Libraries or Applications
138
139 3.1. Kamailio Modules
140
141    The following modules must be loaded before this module:
142      * No dependencies on other Kamailio modules. Note that many modules
143        publish pseudovariables that you can use in this module. The core
144        module for this is the pv module.
145
146 3.2. External Libraries or Applications
147
148    The following libraries or applications must be installed before
149    running Kamailio with this module loaded:
150      * None.
151
152 4. Parameters
153
154    4.1. buf_size (integer)
155    4.2. force_color (integer)
156    4.3. long_format (integer)
157    4.4. prefix (str)
158    4.5. log_facility (string)
159    4.6. log_colors (string)
160    4.7. methods_filter (int)
161
162 4.1. buf_size (integer)
163
164    Maximum size of the log message.
165
166    Default value is 4096.
167
168    Example 1.1. Set buf_size parameter
169 ...
170 modparam("xlog", "buf_size", 8192)
171 ...
172
173 4.2. force_color (integer)
174
175    When set to 1, forces color codes in log messages even if log_stderror
176    is set to 0.
177
178    Default value is 0.
179
180    Example 1.2. Set force_color parameter
181 ...
182 modparam("xlog", "force_color", 0)
183 ...
184
185 4.3. long_format (integer)
186
187    When set to 1, outputs the configuration file name in xlogl() and
188    xdbgl() before the line number.
189
190    Default value is 0.
191
192    Example 1.3. Set long_format parameter
193 ...
194 modparam("xlog", "long_format", 1)
195 ...
196
197 4.4. prefix (str)
198
199    Prefix to be output before the log message.
200
201    Default value is "<script>: ".
202
203    Example 1.4. Set prefix parameter
204 ...
205 modparam("xlog", "prefix", "-xlog: ")
206 ...
207
208 4.5. log_facility (string)
209
210    Syslog facility to be used for the xlog output. By setting this, and
211    configuring syslog, you can get the xlog messages in a separate syslog
212    file than the debug messages issued from the source code.
213
214    Default value is NULL (unset - use same facility as source code debug
215    messages).
216
217    Example 1.5. log_facility example
218 modparam("xlog", "log_facility", "LOG_DAEMON")
219
220 4.6. log_colors (string)
221
222    Update terminal colors used by the Kamailio core for log levels (when
223    log_stderr=1 and log_color=1). The value has to be 'logname=colors',
224    where colors is two characters specifying foreground and background in
225    the same format as $C(xy) variable.
226
227    The parameter can be set many times. The value can also be a
228    ';'-separated list of color specifications.
229
230    Default value is NULL.
231
232    Example 1.6. log_colors example
233 modparam("xlog", "log_colors", "L_ERR=cr")
234 modparam("xlog", "log_colors", "L_ERR=cr;L_WARN=px")
235
236 4.7. methods_filter (int)
237
238    The bitmask with internal SIP method ids to be ignored by xlogm()
239    function. The value can be changed at runtime via cfg reload framework:
240 ...
241 kamcmd cfg.set_now_int xlog methods_filter 15
242 ...
243
244    To see the associated internal ids for SIP requests, look in source
245    tree inside parser/msg_parser.h for enum request_method.
246
247    Default value is -1 (all SIP methods are ignored).
248
249    Example 1.7. Set methods_filter parameter
250 ...
251 modparam("xlog", "long_format", 1)
252 ...
253
254 5. Functions
255
256    5.1. xlog([ [facility,] level,] format)
257    5.2. xdbg(format)
258    5.3. xinfo(format)
259    5.4. xnotice(format)
260    5.5. xwarn(format)
261    5.6. xerr(format)
262    5.7. xbug(format)
263    5.8. xcrit(format)
264    5.9. xalert(format)
265    5.10. xlogl([ [facility,] level,] format)
266    5.11. xdbgl(format)
267    5.12. xlogm(level, format)
268
269 5.1.  xlog([ [facility,] level,] format)
270
271    Output a formated log message.
272
273    Meaning of the parameters are as follows:
274      * facility - The syslog facility that will be used for this single
275        log message.
276        If this parameter is missing, the implicit facility is either the
277        facility set with the 'log_facility' module parameter or the core's
278        log facility.
279      * level - The level that will be used in LOG function. It can be:
280           + L_ALERT - log level -5
281           + L_BUG - log level -4
282           + L_CRIT - log level -3
283           + L_ERR - log level -1
284           + L_WARN - log level 0
285           + L_NOTICE - log level 1
286           + L_INFO - log level 2
287           + L_DBG - log level 3
288           + $pv - any valid pseudo-variable, that has an integer value.
289             See above options for valid log levels.
290        If it is not a pseudo-variable, then what really matters is the
291        third letter of the value. If the log level is higher than the
292        “debug” global parameter, the message is not printed to syslog.
293        If this parameter is missing, the implicit log level is 'L_ERR'.
294      * format - The formatted string to be printed.
295
296    This function can be used from ANY_ROUTE.
297
298    Example 1.8. xlog usage
299 ...
300 xlog("L_ERR", "time [$Tf] method ($rm) r-uri ($ru) 2nd via ($hdr(via[1]))\n");
301 ...
302 xlog("time [$Tf] method ($rm) r-uri ($ru) 2nd via ($hdr(via[1]))\n");
303 ...
304 $var(loglevel) = 2;
305 xlog("$var(loglevel)", "time [$Tf] method ($rm) r-uri ($ru)\n");
306 ...
307 xlog("LOG_LOCAL3", "L_ERR", "this message will be sent to syslog facility LOG_LO
308 CAL3\n");
309 ...
310
311 5.2.  xdbg(format)
312
313    Print a formatted message using DBG function.
314
315    Meaning of the parameters is as follows:
316      * format - The formatted string to be printed.
317
318    This function can be used from ANY_ROUTE.
319
320    Example 1.9. xdbg usage
321 ...
322 xdbg("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
323 ...
324
325 5.3.  xinfo(format)
326
327    Print a formatted log message at L_INFO level.
328
329    Meaning of the parameters is as follows:
330      * format - The formatted string to be printed.
331
332    This function can be used from ANY_ROUTE.
333
334    Example 1.10. xinfo usage
335 ...
336 xinfo("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
337 ...
338
339 5.4.  xnotice(format)
340
341    Print a formatted log message at L_NOTICE level.
342
343    Meaning of the parameters is as follows:
344      * format - The formatted string to be printed.
345
346    This function can be used from ANY_ROUTE.
347
348    Example 1.11. xnotice usage
349 ...
350 xnotice("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
351 ...
352
353 5.5.  xwarn(format)
354
355    Print a formatted log message at L_WARN level.
356
357    Meaning of the parameters is as follows:
358      * format - The formatted string to be printed.
359
360    This function can be used from ANY_ROUTE.
361
362    Example 1.12. xwarn usage
363 ...
364 xwarn("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
365 ...
366
367 5.6.  xerr(format)
368
369    Print a formatted log message at L_ERR level.
370
371    Meaning of the parameters is as follows:
372      * format - The formatted string to be printed.
373
374    This function can be used from ANY_ROUTE.
375
376    Example 1.13. xerr usage
377 ...
378 xerr("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
379 ...
380
381 5.7.  xbug(format)
382
383    Print a formatted log message at L_BUG level.
384
385    Meaning of the parameters is as follows:
386      * format - The formatted string to be printed.
387
388    This function can be used from ANY_ROUTE.
389
390    Example 1.14. xbug usage
391 ...
392 xbug("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
393 ...
394
395 5.8.  xcrit(format)
396
397    Print a formatted log message at L_CRIT level.
398
399    Meaning of the parameters is as follows:
400      * format - The formatted string to be printed.
401
402    This function can be used from ANY_ROUTE.
403
404    Example 1.15. xcrit usage
405 ...
406 xcrit("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
407 ...
408
409 5.9.  xalert(format)
410
411    Print a formatted log message at L_ALERT level.
412
413    Meaning of the parameters is as follows:
414      * format - The formatted string to be printed.
415
416    This function can be used from ANY_ROUTE.
417
418    Example 1.16. xalert usage
419 ...
420 xalert("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
421 ...
422
423 5.10.  xlogl([ [facility,] level,] format)
424
425    Similar to xlog(), in addition prints configuration file line number at
426    the beginning of message.
427
428 5.11.  xdbgl(format)
429
430    Similar to xdbg(), in addition prints configuration file line number at
431    the beginning of message.
432
433 5.12.  xlogm(level, format)
434
435    Similar to xlog(level, format), but skips writing the log messages for
436    SIP requests and responses that match the SIP method id with
437    methods_filter parameter value.