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