b03b8ecd586548ab417e84873a5d78a39aab7b1c
[sip-router] / src / modules / xlog / doc / xlog_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section id="xlog.overview">
17         <title>Overview</title>
18         <para>
19                 This module provides the possibility to print user formatted log or
20                 debug messages from &kamailio; scripts, similar to the printf function. 
21                 A C-style printf specifier is replaced with a part of the &sip; request or other
22                 variables from system.
23         </para>
24         </section>
25         <section id="sec-implemented-specifiers">
26         <title>Implemented Specifiers</title>
27         <para>
28         In the xlog function, you use pseudo-variables, that are a part
29         of &kamailio; core and are used by other modules as well (e.g., <emphasis>avpops</emphasis>
30         in the function <function>avp_printf()</function>)
31         </para>
32         <para>
33         The most important changes from earlier versions of &kamailio; are:
34         </para>
35         <itemizedlist>
36                 <listitem>
37                 <para>
38                 - '%' has been replaced by '$'
39                 </para>
40                 </listitem>
41                 <listitem>
42                 <para>
43                 - to print a header, use $hdr(header_name[index]) instead of
44                 %{header_name[index]}
45                 </para>
46                 </listitem>
47                 <listitem>
48                 <para>
49                 - to print an AVP, use now $avp([si]:avp_id[index]) instead of
50                 %{[si]:avp_id[index]} or $avp([$avp_alias[index]) instead of
51                 %{[$avp_alias[index]}
52                 </para>
53                 </listitem>
54         </itemizedlist>
55         <para>
56         The full list of available pseudo-variables in &kamailio; is
57         available at:
58         <ulink url="http://kamailio.org/wiki/">
59         http://kamailio.org/wiki/</ulink>
60         </para>
61         </section>
62         <section>
63         <title>Dependencies</title>
64         <section>
65                 <title>&kamailio; Modules</title>
66                 <para>
67                 The following modules must be loaded before this module:
68                         <itemizedlist>
69                         <listitem>
70                         <para>
71                                 <emphasis>No dependencies on other &kamailio; modules</emphasis>.
72                                 Note that many modules publish pseudovariables that you can use
73                                 in this module. The core module for this is the <emphasis>pv</emphasis> module.
74                         </para>
75                         </listitem>
76                         </itemizedlist>
77                 </para>
78         </section>
79         <section>
80                 <title>External Libraries or Applications</title>
81                 <para>
82                 The following libraries or applications must be installed before running
83                 &kamailio; with this module loaded:
84                         <itemizedlist>
85                         <listitem>
86                         <para>
87                                 <emphasis>None</emphasis>.
88                         </para>
89                         </listitem>
90                         </itemizedlist>
91                 </para>
92         </section>
93         </section>
94         <section>
95         <title>Parameters</title>
96         <section id="xlog.p.buf_size">
97                 <title><varname>buf_size</varname> (integer)</title>
98                 <para>
99                 Maximum size of the log message.
100                 </para>
101                 <para>
102                 <emphasis>
103                         Default value is 4096.
104                 </emphasis>
105                 </para>
106                 <example>
107                 <title>Set <varname>buf_size</varname> parameter</title>
108                 <programlisting format="linespecific">
109 ...
110 modparam("xlog", "buf_size", 8192)
111 ...
112 </programlisting>
113                 </example>
114         </section>
115         <section id="xlog.p.force_color">
116                 <title><varname>force_color</varname> (integer)</title>
117                 <para>
118                 When set to 1, forces color codes in log messages even if <varname>log_stderror</varname> is set to 0.
119                 </para>
120                 <para>
121                 <emphasis>
122                         Default value is 0.
123                 </emphasis>
124                 </para>
125                 <example>
126                 <title>Set <varname>force_color</varname> parameter</title>
127                 <programlisting format="linespecific">
128 ...
129 modparam("xlog", "force_color", 0)
130 ...
131 </programlisting>
132                 </example>
133         </section>
134         <section id="xlog.p.long_format">
135                 <title><varname>long_format</varname> (integer)</title>
136                 <para>
137                 When set to 1, outputs the configuration file name in xlogl() and xdbgl()
138                 before the line number.
139                 </para>
140                 <para>
141                 <emphasis>
142                         Default value is 0.
143                 </emphasis>
144                 </para>
145                 <example>
146                 <title>Set <varname>long_format</varname> parameter</title>
147                 <programlisting format="linespecific">
148 ...
149 modparam("xlog", "long_format", 1)
150 ...
151 </programlisting>
152                 </example>
153         </section>
154         <section id="xlog.p.varname">
155                 <title><varname>prefix</varname> (str)</title>
156                 <para>
157                 Prefix to be output before the log message.
158                 </para>
159                 <para>
160                 <emphasis>
161                         Default value is "&lt;script&gt;: ".
162                 </emphasis>
163                 </para>
164                 <example>
165                 <title>Set <varname>prefix</varname> parameter</title>
166                 <programlisting format="linespecific">
167 ...
168 modparam("xlog", "prefix", "-xlog: ")
169 ...
170 </programlisting>
171                 </example>
172         </section>
173         <section id="xlog.p.log_facility">
174                 <title><varname>log_facility</varname> (string)</title>
175                 <para>
176                 Syslog facility to be used for the xlog output.
177                 By setting this, and configuring syslog, you can get the xlog messages 
178                 in a separate syslog file than the debug messages issued from the source code.
179                 </para>
180                 <para>
181                 Default value is NULL (unset - use same facility as source code debug
182                 messages).
183                 </para>
184                 <example>
185                 <title>log_facility example</title>
186                 <programlisting format="linespecific">
187 modparam("xlog", "log_facility", "LOG_DAEMON")
188 </programlisting>
189                 </example>
190         </section>
191         <section id="xlog.p.log_colors">
192                 <title><varname>log_colors</varname> (string)</title>
193                 <para>
194                 Update terminal colors used by the &kamailio; core for log levels (when log_stderr=1
195                 and log_color=1). The value has to be 'logname=colors', where colors
196                 is two characters specifying foreground and background in the same
197                 format as $C(xy) variable.
198                 </para>
199                 <para>
200                 The parameter can be set many times. The value can also be a
201                 ';'-separated list of color specifications.
202                 </para>
203                 <para>
204                 Default value is NULL.
205                 </para>
206                 <example>
207                 <title>log_colors example</title>
208                 <programlisting format="linespecific">
209 modparam("xlog", "log_colors", "L_ERR=cr")
210 modparam("xlog", "log_colors", "L_ERR=cr;L_WARN=px")
211 </programlisting>
212                 </example>
213         </section>
214         <section id="xlog.p.methods_filter">
215                 <title><varname>methods_filter</varname> (int)</title>
216                 <para>
217                 The bitmask with internal SIP method ids to be ignored by
218                 xlogm() function. The value can be changed at runtime via
219                 cfg reload framework:
220                 </para>
221                 <programlisting format="linespecific">
222 ...
223 kamcmd cfg.set_now_int xlog methods_filter 15
224 ...
225 </programlisting>
226                 <para>
227                 To see the associated internal ids for SIP requests, look
228                 in source tree inside parser/msg_parser.h for enum request_method.
229                 </para>
230                 <para>
231                 <emphasis>
232                         Default value is -1 (all SIP methods are ignored).
233                 </emphasis>
234                 </para>
235                 <example>
236                 <title>Set <varname>methods_filter</varname> parameter</title>
237                 <programlisting format="linespecific">
238 ...
239 modparam("xlog", "long_format", 1)
240 ...
241 </programlisting>
242                 </example>
243         </section>
244
245         </section>
246         <section>
247         <title>Functions</title>
248         <section id="xlog.f.xlog">
249                 <title>
250                 <function moreinfo="none">xlog([ [facility,] level,] format)</function>
251                 </title>
252                 <para>
253                 Output a formated log message.
254                 </para>
255                 <para>Meaning of the parameters are as follows:</para>
256                 <itemizedlist>
257                 <listitem>
258                         <para><emphasis>facility</emphasis> - The syslog facility that will be used for this single log message.
259                         </para>
260                         <para>
261                         If this parameter is missing, the implicit facility is either the facility set with
262                         the 'log_facility' module parameter or the core's log facility.
263                         </para>
264                 </listitem>
265                 <listitem>
266                         <para><emphasis>level</emphasis> - The level that will be used in LOG function. It can be:
267                         </para>
268                         <itemizedlist>
269                         <listitem>
270                                 <para>
271                                 L_ALERT - log level -5
272                                 </para>
273                         </listitem>
274                         <listitem>
275                                 <para>
276                                 L_BUG - log level -4
277                                 </para>
278                         </listitem>
279                         <listitem>
280                                 <para>
281                                 L_CRIT - log level -3
282                                 </para>
283                         </listitem>
284                         <listitem>
285                                 <para>
286                                 L_ERR - log level -1
287                                 </para>
288                         </listitem>
289                         <listitem>
290                                 <para>
291                                 L_WARN - log level 0
292                                 </para>
293                         </listitem>
294                         <listitem>
295                                 <para>
296                                 L_NOTICE - log level 1
297                                 </para>
298                         </listitem>
299                         <listitem>
300                                 <para>
301                                 L_INFO - log level 2
302                                 </para>
303                         </listitem>
304                         <listitem>
305                                 <para>
306                                 L_DBG - log level 3
307                                 </para>
308                         </listitem>
309                         <listitem>
310                                 <para>
311                                 $pv - any valid pseudo-variable, that has an integer value.
312                                 See above options for valid log levels.
313                                 </para>
314                         </listitem>
315                         </itemizedlist>
316                         <para>
317                         If it is not a pseudo-variable, then what really matters is the
318                         third letter of the value. If the log level is higher than the
319                         <quote>debug</quote> global parameter, the message is not printed
320                         to syslog.
321                         </para>
322                         <para>
323                         If this parameter is missing, the implicit log level is 'L_ERR'.
324                         </para>
325                 </listitem>
326                 <listitem>
327                         <para><emphasis>format</emphasis> - The formatted string to be printed. 
328                         </para>
329                 </listitem>
330                 </itemizedlist>
331                 <para>
332                 This function can be used from ANY_ROUTE.
333                 </para>
334                 <example>
335                 <title><function>xlog</function> usage</title>
336                 <programlisting format="linespecific">
337 ...
338 xlog("L_ERR", "time [$Tf] method ($rm) r-uri ($ru) 2nd via ($hdr(via[1]))\n");
339 ...
340 xlog("time [$Tf] method ($rm) r-uri ($ru) 2nd via ($hdr(via[1]))\n");
341 ...
342 $var(loglevel) = 2;
343 xlog("$var(loglevel)", "time [$Tf] method ($rm) r-uri ($ru)\n");
344 ...
345 xlog("LOG_LOCAL3", "L_ERR", "this message will be sent to syslog facility LOG_LOCAL3\n");
346 ...
347 </programlisting>
348                 </example>
349         </section>
350
351         <section id="xlog.f.xdbg">
352                 <title>
353                 <function moreinfo="none">xdbg(format)</function>
354                 </title>
355                 <para>
356                 Print a formatted message using DBG function.
357                 </para>
358                 <para>Meaning of the parameters is as follows:</para>
359                 <itemizedlist>
360                 <listitem>
361                         <para><emphasis>format</emphasis> - The formatted string to be printed.
362                         </para>
363                 </listitem>
364                 </itemizedlist>
365                 <para>
366                 This function can be used from ANY_ROUTE.
367                 </para>
368
369                 <example>
370                 <title><function>xdbg</function> usage</title>
371                 <programlisting format="linespecific">
372 ...
373 xdbg("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
374 ...
375 </programlisting>
376                 </example>
377         </section>
378
379         <section id="xlog.f.xinfo">
380                 <title>
381                 <function moreinfo="none">xinfo(format)</function>
382                 </title>
383                 <para>
384                 Print a formatted log message at L_INFO level.
385                 </para>
386                 <para>Meaning of the parameters is as follows:</para>
387                 <itemizedlist>
388                 <listitem>
389                         <para><emphasis>format</emphasis> - The formatted string to be printed.
390                         </para>
391                 </listitem>
392                 </itemizedlist>
393                 <para>
394                 This function can be used from ANY_ROUTE.
395                 </para>
396
397                 <example>
398                 <title><function>xinfo</function> usage</title>
399                 <programlisting format="linespecific">
400 ...
401 xinfo("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
402 ...
403 </programlisting>
404                 </example>
405         </section>
406
407         <section id="xlog.f.xnotice">
408                 <title>
409                 <function moreinfo="none">xnotice(format)</function>
410                 </title>
411                 <para>
412                 Print a formatted log message at L_NOTICE level.
413                 </para>
414                 <para>Meaning of the parameters is as follows:</para>
415                 <itemizedlist>
416                 <listitem>
417                         <para><emphasis>format</emphasis> - The formatted string to be printed.
418                         </para>
419                 </listitem>
420                 </itemizedlist>
421                 <para>
422                 This function can be used from ANY_ROUTE.
423                 </para>
424
425                 <example>
426                 <title><function>xnotice</function> usage</title>
427                 <programlisting format="linespecific">
428 ...
429 xnotice("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
430 ...
431 </programlisting>
432                 </example>
433         </section>
434
435         <section id="xlog.f.xwarn">
436                 <title>
437                 <function moreinfo="none">xwarn(format)</function>
438                 </title>
439                 <para>
440                 Print a formatted log message at L_WARN level.
441                 </para>
442                 <para>Meaning of the parameters is as follows:</para>
443                 <itemizedlist>
444                 <listitem>
445                         <para><emphasis>format</emphasis> - The formatted string to be printed.
446                         </para>
447                 </listitem>
448                 </itemizedlist>
449                 <para>
450                 This function can be used from ANY_ROUTE.
451                 </para>
452
453                 <example>
454                 <title><function>xwarn</function> usage</title>
455                 <programlisting format="linespecific">
456 ...
457 xwarn("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
458 ...
459 </programlisting>
460                 </example>
461         </section>
462
463         <section id="xlog.f.xerr">
464                 <title>
465                 <function moreinfo="none">xerr(format)</function>
466                 </title>
467                 <para>
468                 Print a formatted log message at L_ERR level.
469                 </para>
470                 <para>Meaning of the parameters is as follows:</para>
471                 <itemizedlist>
472                 <listitem>
473                         <para><emphasis>format</emphasis> - The formatted string to be printed.
474                         </para>
475                 </listitem>
476                 </itemizedlist>
477                 <para>
478                 This function can be used from ANY_ROUTE.
479                 </para>
480
481                 <example>
482                 <title><function>xerr</function> usage</title>
483                 <programlisting format="linespecific">
484 ...
485 xerr("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
486 ...
487 </programlisting>
488                 </example>
489         </section>
490
491         <section id="xlog.f.xbug">
492                 <title>
493                 <function moreinfo="none">xbug(format)</function>
494                 </title>
495                 <para>
496                 Print a formatted log message at L_BUG level.
497                 </para>
498                 <para>Meaning of the parameters is as follows:</para>
499                 <itemizedlist>
500                 <listitem>
501                         <para><emphasis>format</emphasis> - The formatted string to be printed.
502                         </para>
503                 </listitem>
504                 </itemizedlist>
505                 <para>
506                 This function can be used from ANY_ROUTE.
507                 </para>
508
509                 <example>
510                 <title><function>xbug</function> usage</title>
511                 <programlisting format="linespecific">
512 ...
513 xbug("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
514 ...
515 </programlisting>
516                 </example>
517         </section>
518
519         <section id="xlog.f.xcrit">
520                 <title>
521                 <function moreinfo="none">xcrit(format)</function>
522                 </title>
523                 <para>
524                 Print a formatted log message at L_CRIT level.
525                 </para>
526                 <para>Meaning of the parameters is as follows:</para>
527                 <itemizedlist>
528                 <listitem>
529                         <para><emphasis>format</emphasis> - The formatted string to be printed.
530                         </para>
531                 </listitem>
532                 </itemizedlist>
533                 <para>
534                 This function can be used from ANY_ROUTE.
535                 </para>
536
537                 <example>
538                 <title><function>xcrit</function> usage</title>
539                 <programlisting format="linespecific">
540 ...
541 xcrit("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
542 ...
543 </programlisting>
544                 </example>
545         </section>
546
547         <section id="xlog.f.xalert">
548                 <title>
549                 <function moreinfo="none">xalert(format)</function>
550                 </title>
551                 <para>
552                 Print a formatted log message at L_ALERT level.
553                 </para>
554                 <para>Meaning of the parameters is as follows:</para>
555                 <itemizedlist>
556                 <listitem>
557                         <para><emphasis>format</emphasis> - The formatted string to be printed.
558                         </para>
559                 </listitem>
560                 </itemizedlist>
561                 <para>
562                 This function can be used from ANY_ROUTE.
563                 </para>
564
565                 <example>
566                 <title><function>xalert</function> usage</title>
567                 <programlisting format="linespecific">
568 ...
569 xalert("time $Cbx[$Tf]$Cxx method ($rm) r-uri ($ru)\n");
570 ...
571 </programlisting>
572                 </example>
573         </section>
574
575         <section id="xlog.f.xlogl">
576                 <title>
577                 <function moreinfo="none">xlogl([ [facility,] level,] format)</function>
578                 </title>
579                 <para>
580                 Similar to xlog(), in addition prints configuration file line number
581                 at the beginning of message.
582                 </para>
583         </section>
584         <section id="xlog.f.xdbgl">
585                 <title>
586                 <function moreinfo="none">xdbgl(format)</function>
587                 </title>
588                 <para>
589                 Similar to xdbg(), in addition prints configuration file line number
590                 at the beginning of message.
591                 </para>
592         </section>
593         <section id="xlog.f.xlogm">
594                 <title>
595                 <function moreinfo="none">xlogm(level, format)</function>
596                 </title>
597                 <para>
598                         Similar to xlog(level, format), but skips writing the log messages
599                         for SIP requests and responses that match the SIP method id with
600                         methods_filter parameter value.
601                 </para>
602         </section>
603         </section>
604 </chapter>
605