siptrace: docs for trace_db_mode parameter
[sip-router] / src / modules / siptrace / doc / siptrace_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>
17         <title>Overview</title>
18         <para>
19                 The SIPtrace module offer a possibility to store incoming and outgoing SIP
20                 messages in a database and/or duplicate to the capturing server (using <acronym>HEP</acronym>,
21                 the Homer encapsulation protocol, or plain SIP mode). Since version 5.3.0 new levels of tracing
22                 are available. Transactions and dialogs can be traced.
23         </para>
24         <para>
25                 There are multiple ways of storing information:
26                 <itemizedlist>
27                 <listitem>
28                 <para>
29                 by calling the sip_trace() method explicitly in the &kamailio; configuration
30                 file. In this case the original message is processed along with it's corresponding
31                 transaction/dialog if certain flags are used.
32                 </para>
33                 </listitem>
34                 <listitem>
35                 <para>
36                 by setting <quote>trace_mode</quote> to mirror or store to db all traffic.
37                 </para>
38                 </listitem>
39                 </itemizedlist>
40         </para>
41
42         <para>
43         The tracing can be turned on/off using Kamailio <acronym>RPC</acronym> commands.
44         </para>
45         <para>
46         &ctltool; rpc siptrace.status on
47         </para>
48         <para>
49         &ctltool; rpc siptrace.status off
50         </para>
51         </section>
52         <section>
53         <title>Dependencies</title>
54         <section>
55                 <title>&kamailio; Modules</title>
56                 <para>
57                 The following modules must be conditionally loaded before this module:
58                         <itemizedlist>
59                         <listitem>
60                         <para>
61                                 <emphasis>A database module</emphasis> - Mysql, Postgres,
62                                 dbtext, unixODBC... Optional, if tracing to DB is enabled.
63                         </para>
64                         </listitem>
65                         <listitem>
66                         <para>
67                                 <emphasis>dialog, tm and sl modules</emphasis> - optional, only if
68                                 you want to trace messages forwarded by these modules.
69                         </para>
70                         </listitem>
71                         </itemizedlist>
72                 </para>
73         </section>
74         <section>
75                 <title>External Libraries or Applications</title>
76                 <para>
77                 The following libraries or applications must be installed before running
78                 &kamailio; with this module loaded:
79                         <itemizedlist>
80                         <listitem>
81                         <para>
82                                 <emphasis>None</emphasis>.
83                         </para>
84                         </listitem>
85                         </itemizedlist>
86                 </para>
87         </section>
88         </section>
89         <section>
90         <title>Parameters</title>
91         <section id="siptrace.p.db_url">
92                 <title><varname>db_url</varname> (str)</title>
93                 <para>
94                 Database URL.
95                 </para>
96                 <para>
97                 <emphasis>
98                         Default value is "&defaultdb;".
99                 </emphasis>
100                 </para>
101                 <example>
102                 <title>Set <varname>db_url</varname> parameter</title>
103                 <programlisting format="linespecific">
104 ...
105 modparam("siptrace", "db_url", "&exampledb;")
106 ...
107 </programlisting>
108                 </example>
109         </section>
110         <section id="siptrace.p.table">
111                 <title><varname>table</varname> (str)</title>
112                 <para>
113                 Name of the table where to store the SIP messages.
114                 </para>
115                 <para>
116                 <emphasis>
117                         Default value is <quote>sip_trace</quote>.
118                 </emphasis>
119                 </para>
120                 <example>
121                 <title>Set <varname>table</varname> parameter</title>
122                 <programlisting format="linespecific">
123 ...
124 modparam("siptrace", "table", "strace")
125 ...
126 </programlisting>
127                 </example>
128         </section>
129         <section id="siptrace.p.trace_flag">
130                 <title><varname>trace_flag</varname> (integer)</title>
131                 <para>
132                 Which flag is used to mark messages to trace without
133                 traced user.
134                 </para>
135                 <para>
136                 <emphasis>
137                         Default value is "0".
138                 </emphasis>
139                 </para>
140                 <example>
141                 <title>Set <varname>trace_flag</varname> parameter</title>
142                 <programlisting format="linespecific">
143 ...
144 modparam("siptrace", "trace_flag", 22)
145 ...
146 </programlisting>
147                 </example>
148         </section>
149         <section id="siptrace.p.trace_on">
150                 <title><varname>trace_on</varname> (integer)</title>
151                 <para>
152                 Parameter to enable/disable trace (on(1)/off(0))
153                 </para>
154                 <para>
155                 <emphasis>
156                         Default value is "0".
157                 </emphasis>
158                 </para>
159                 <example>
160                 <title>Set <varname>trace_on</varname> parameter</title>
161                 <programlisting format="linespecific">
162 ...
163 modparam("siptrace", "trace_on", 1)
164 ...
165 </programlisting>
166                 </example>
167         </section>
168         <section id="siptrace.p.traced_user_avp">
169                 <title><varname>traced_user_avp</varname> (str)</title>
170                 <para>
171                 The name of the <acronym>AVP</acronym> storing the SIP URI of the traced user. If
172                 the AVP is set, messages are stored in database table and
173                 the <quote>traced_user</quote> column is filled with AVP's value. You can store
174                 the message many times for many users by having multiple values
175                 for this AVP.
176                 </para>
177                 <para>
178                 <emphasis>
179                         Default value is "NULL" (feature disabled).
180                 </emphasis>
181                 </para>
182                 <example>
183                 <title>Set <varname>traced_user_avp</varname> parameter</title>
184                 <programlisting format="linespecific">
185 ...
186 modparam("siptrace", "traced_user_avp", "$avp(user)")
187 ...
188 </programlisting>
189                 </example>
190         </section>
191         <section id="siptrace.p.trace_table_avp">
192                 <title><varname>trace_table_avp</varname> (str)</title>
193                 <para>
194                 The name of the AVP storing the name of the table where to
195                 store the SIP messages. If it is not set, the value of
196                 <quote>table</quote> parameter is used. In this way one can select
197                 dynamically where to store the traced messages. The table
198                 must exist, and must have the same structure as the <quote>sip_trace</quote>
199                 table.
200                 </para>
201                 <para>
202                 <emphasis>
203                         Default value is "NULL" (feature disabled).
204                 </emphasis>
205                 </para>
206                 <example>
207                 <title>Set <varname>trace_table_avp</varname> parameter</title>
208                 <programlisting format="linespecific">
209 ...
210 modparam("siptrace", "trace_table_avp", "$avp(i:345)")
211 modparam("siptrace", "trace_table_avp", "$avp(s:siptrace_table)")
212 ...
213 </programlisting>
214                 </example>
215         </section>
216         <section id="siptrace.p.duplicate_uri">
217                 <title><varname>duplicate_uri</varname> (str)</title>
218                 <para>
219                 The address in form of a SIP URI where to send a duplicate
220                 of traced message.
221                 </para>
222                 <para>
223                 <emphasis>
224                         Default value is "NULL".
225                 </emphasis>
226                 </para>
227                 <example>
228                 <title>Set <varname>duplicate_uri</varname> parameter</title>
229                 <programlisting format="linespecific">
230 ...
231 modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
232 ...
233 </programlisting>
234                 </example>
235         </section>
236         <section id="siptrace.p.trace_to_database">
237                 <title><varname>trace_to_database</varname> (integer)</title>
238                 <para>
239                 Parameter to enable/disable inserts to the database from this
240                 &kamailio;.
241                 </para>
242                 <para>
243                 In case we only want to send the SIP messages to the
244                 <quote>duplicate_uri</quote> and not store the information to the local
245                 database we can set this to "0".
246                 </para>
247                 <para>
248                 <emphasis>
249                         Default value is "1".
250                 </emphasis>
251                 </para>
252                 <example>
253                 <title>Set <varname>trace_to_database</varname> parameter</title>
254                 <programlisting format="linespecific">
255 ...
256 modparam("siptrace", "trace_to_database", 0)
257 ...
258 </programlisting>
259                 </example>
260         </section>
261         <section id="siptrace.p.trace_local_ip">
262                 <title><varname>trace_local_ip</varname> (str)</title>
263                 <para>
264                 The address to be used in <quote>fromip</quote> field for
265                 locally generated messages. If not set, the module sets it to the address
266                 of the socket that will be used to send the message.
267                 </para>
268                 <para>
269                 <emphasis>
270                         Default value is "NULL".
271                 </emphasis>
272                 </para>
273                 <example>
274                 <title>Set <varname>trace_local_ip</varname> parameter</title>
275                 <programlisting format="linespecific">
276 ...
277 modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
278 ...
279 </programlisting>
280                 </example>
281         </section>
282         <section id="siptrace.p.trace_sl_acks">
283                 <title><varname>trace_sl_acks</varname> (integer)</title>
284                 <para>
285                 Parameter to enable/disable tracing of SL-filtered ACKs (on=1
286                 / off=0).
287                 </para>
288                 <para>
289                 By default all ACKs to replies generated by SL module are traced. There
290                 is no way to select among them. The SL module is able to run an event
291                 route when such an ACK arrives (<emphasis>event_route[sl:filtered-ack]</emphasis>).
292                 You can set this parameter to 0 and then execute sip_trace() in the event route,
293                 accompanied by config rules to decide which ACK to trace.
294                 </para>
295                 <para>
296                 <emphasis>
297                         Default value is "1".
298                 </emphasis>
299                 </para>
300                 <example>
301                 <title>Set <varname>trace_sl_acks</varname> parameter</title>
302                 <programlisting format="linespecific">
303 ...
304 modparam("siptrace", "trace_sl_acks", 0)
305 ...
306 </programlisting>
307                 </example>
308         </section>
309          <section id="siptrace.p.xheaders_write">
310                 <title><varname>xheaders_write</varname> (integer)</title>
311                 <para>
312                 Parameter to enable/disable writing of x-headers.
313                 </para>
314                 <para>
315                 Stores <quote>fromip</quote>, <quote>toip</quote>, <quote>method</quote> and
316                 <quote>direction</quote> in <quote>X-Siptrace-*</quote> headers.
317                 This allows to transmit them to a second &kamailio; server
318                 using the <quote>duplicate_uri</quote> feature.
319                 Because the headers are added after the data is written to the database,
320                 the headers only show up in the packets sent by duplicate_uri.
321                 </para>
322                 <para>
323                 See <varname>xheaders_read</varname>, it should be used on the receiving
324                 side.
325                 </para>
326                 <para>
327                 <emphasis>Note:</emphasis> The headers are first read, then written. This allows
328                 relaying the information over more than two &kamailio; servers by setting both
329                 <varname>xheaders_write</varname> and <varname>xheaders_read</varname>
330                 to "1" on the servers in the middle.
331                 </para>
332                 <para>
333                 <emphasis>
334                         Default value is "0".
335                 </emphasis>
336                 </para>
337                 <example>
338                 <title>Set <varname>xheaders_write</varname> parameter</title>
339                 <programlisting format="linespecific">
340 ...
341 modparam("siptrace", "xheaders_write", 0)
342 ...
343 </programlisting>
344                 </example>
345         </section>
346          <section id="siptrace.p.xheaders_read">
347                 <title><varname>xheaders_read</varname> (integer)</title>
348                 <para>
349                 Parameter to enable/disable reading of x-headers.
350                 </para>
351                 <para>
352                 Reads and removes the <quote>X-Siptrace-*</quote> headers. Packets not containing the
353                 headers are neither stored to the database nor relayed (duplicate_uri).
354                 See <varname>xheaders_write</varname> for further information.
355                 </para>
356                 <para>
357                 <emphasis>
358                         Default value is "0".
359                 </emphasis>
360                 </para>
361                 <example>
362                 <title>Set <varname>xheaders_read</varname> parameter</title>
363                 <programlisting format="linespecific">
364 ...
365 modparam("siptrace", "xheaders_read", 0)
366 ...
367 </programlisting>
368                 </example>
369         </section>
370         <section id="siptrace.p.hep_mode_on">
371                 <title><varname>hep_mode_on</varname> (integer)</title>
372                 <para>
373                 Parameter to enable/disable Homer encapsulate mode (on(1)/off(0))
374                 </para>
375                 <para>
376                 <emphasis>
377                         Default value is "0".
378                 </emphasis>
379                 </para>
380                 <example>
381                 <title>Set <varname>hep_mode_on</varname> parameter</title>
382                 <programlisting format="linespecific">
383 ...
384 modparam("siptrace", "hep_mode_on", 1)
385 ...
386 </programlisting>
387                 </example>
388         </section>
389
390         <section id="siptrace.p.hep_version">
391                 <title><varname>hep_version</varname> (integer)</title>
392                 <para>
393                 The parameter indicate the version of the HEP protocol.
394                 Can be <quote>1</quote>, <quote>2</quote> or <quote>3</quote>.
395                 In HEPv2 and HEPv3 the timestamp and capture agent ID will be
396                 included in the HEP header.
397                 </para>
398                 <para>
399                 <emphasis>
400                         Default value is "1".
401                 </emphasis>
402                 </para>
403                 <example>
404                 <title>Set <varname>hep_version</varname> parameter</title>
405                 <programlisting format="linespecific">
406 ...
407 modparam("siptrace", "hep_version", 3)
408 ...
409 </programlisting>
410                 </example>
411         </section>
412         <section id="siptrace.p.hep_capture_id">
413                 <title><varname>hep_capture_id</varname> (integer)</title>
414                 <para>
415                 The parameter indicate the capture agent ID for the <acronym>HEPv2</acronym>
416                 or <acronym>HEPv3</acronym> protocol.
417                 Limitation: 16-bit integer for HEPv2, 32-bit for HEPv3.
418                 </para>
419                 <para>
420                 <emphasis>
421                         Default value is "1".
422                 </emphasis>
423                 </para>
424                 <example>
425                 <title>Set <varname>hep_capture_id</varname> parameter</title>
426                 <programlisting format="linespecific">
427 ...
428 modparam("siptrace", "hep_capture_id", 234)
429 ...
430 </programlisting>
431                 </example>
432         </section>
433         <section id="siptrace.p.trace_db_mode">
434                 <title><varname>trace_db_mode</varname> (integer)</title>
435                 <para>
436                                 If set to 1, the module uses <quote>INSERT DELAYED</quote> to
437                                 store to database (when it is available, otherwise falls back
438                                 to <quote>INSERT</quote>).
439                 </para>
440                 <para>
441                                 If set to 2, the module uses <quote>ASYNC-INSERT</quote> to
442                                 store to database (when it is available, otherwise falls back
443                                 to <quote>INSERT</quote>).
444                 </para>
445                 <para>
446                 Default value is <emphasis>0 (use <quote>INSERT</quote>)</emphasis>.
447                 </para>
448                 <example>
449                 <title>Set <varname>trace_db_mode</varname>
450                 parameter</title>
451                 <programlisting format="linespecific">
452 ...
453 modparam("siptrace", "trace_db_mode", 1)
454 ...
455 </programlisting>
456                 </example>
457         </section>
458         <section id="siptrace.p.trace_delayed">
459                 <title><varname>trace_delayed</varname> (integer)</title>
460                                 <para>
461                                         Kept for backward compatibily, use trace_db_mode instead.
462                 </para>
463                 <para>
464                                         If set to non-zero, ot sets trace_db_mode paremter to 1
465                                         when the module is initialized.
466                 </para>
467                 <para>
468                 Default value is <emphasis>0</emphasis>.
469                 </para>
470                 <example>
471                 <title>Set <varname>trace_delayed</varname>
472                 parameter</title>
473                 <programlisting format="linespecific">
474 ...
475 modparam("siptrace", "trace_delayed", 1)
476 ...
477 </programlisting>
478                 </example>
479         </section>
480         <section id="siptrace.p.send_sock_name">
481                 <title><varname>send_sock_name</varname> (str)</title>
482                 <para>
483                         The name of the local listen socket from where to send
484                         the duplicated traffic via SIP or HEP. In the absence of this parameter
485                         &kamailio; automatically picks an interface. It has priority over
486                         'send_sock_addr' parameter.
487                 </para>
488                 <example>
489                 <title>Set <varname>send_sock_name</varname> parameter</title>
490                 <programlisting format="linespecific">
491 ...
492 modparam("siptrace", "send_sock_name", "sock1")
493 ...
494 </programlisting>
495                 </example>
496         </section>
497         <section id="siptrace.p.send_sock_addr">
498                 <title><varname>send_sock_addr</varname> (str)</title>
499                 <para>
500                         The local interface in the form of SIP URI from where to send
501                         the duplicated traffic. In the absence of this parameter
502                         &kamailio; automatically picks an interface.
503                 </para>
504                 <example>
505                 <title>Set <varname>send_sock_addr</varname> parameter</title>
506                 <programlisting format="linespecific">
507 ...
508 modparam("siptrace", "send_sock_addr", "sip:10.1.1.2:5000")
509 ...
510 </programlisting>
511                 </example>
512         </section>
513         <section id="siptrace.p.force_send_sock">
514                 <title><varname>force_send_sock</varname> (str)</title>
515                                 <para>It is the same as 'send_sock_addr' parameter, this being
516                                 kept for backward compatibility when 'send_sock_name' and
517                                 'send_sock_addr' were introduced.</para>
518         </section>
519
520         <section id="siptrace.p.trace_init_mode">
521                 <title><varname>trace_init_mode</varname> (integer)</title>
522                                 <para>
523                                         Control what tracing modes are initialized.
524                 </para>
525                                 <para>
526                                 The value of the parameter can be a combination of next values:
527                                 <itemizedlist>
528                                 <listitem>
529                 <para>
530                 0 - all modes are initialized.
531                 </para>
532                                 </listitem>
533                                 <listitem>
534                 <para>
535                                 1 - module initialized to do tracing only with core callback
536                                 functions (see also 'trace_mode' parameter).
537                 </para>
538                                 </listitem>
539                                 <listitem>
540                 <para>
541                                 2 - module initialized to do tracing only using config script flags
542                                 and functions.
543                 </para>
544                                 </listitem>
545                                 </itemizedlist>
546                                 </para>
547                 <para>
548                 Default value is <emphasis>0</emphasis>.
549                 </para>
550                 <example>
551                 <title>Set <varname>trace_init_mode</varname> parameter</title>
552                 <programlisting format="linespecific">
553 ...
554 modparam("siptrace", "trace_init_mode", 1)
555 ...
556 </programlisting>
557                 </example>
558         </section>
559         <section id="siptrace.p.trace_mode">
560                 <title><varname>trace_mode</varname> (integer)</title>
561                 <para>
562                                 If not set to 0, the module uses core events triggered when receiving
563                                 or sending SIP traffic to store it to database or mirror it to a SIP
564                                 capture server using HEP or UDP forwarding.
565                                 It will automatically do the handling of all SIP traffic.
566                                 It is no longer needed to set the siptrace flag per request or
567                                 execute sip_trace(), if it is done, then the storing and mirroring is
568                                 duplicated.
569                 </para>
570                                 <para>
571                                 The value of the parameter can be a combination of next values:
572                                 <itemizedlist>
573                                 <listitem>
574                 <para>
575                 0 - no automatic mirroring or storing of SIP traffic.
576                 </para>
577                                 </listitem>
578                                 <listitem>
579                                 <para>
580                                 1 (1st bit set) - mirror the traffic to HEP server.
581                                 </para>
582                                 </listitem>
583                                 <listitem>
584                                 <para>
585                                 2 (2nd bit set) - store the traffic to database server.
586                                 </para>
587                                 </listitem>
588                                 <listitem>
589                                 <para>
590                                 4 (3rd bit set) - mirro the traffic to the SIP URI specified by
591                                 duplicate_uri.
592                                 </para>
593                                 </listitem>
594                                 </itemizedlist>
595                                 </para>
596                 <para>
597                 The trace_on parameter still has to be set, allowing also to control
598                 this mode of mirroring via RPC commands.
599                 </para>
600                 <para>
601                 Default value is <emphasis>0</emphasis>.
602                 </para>
603                 <example>
604                 <title>Set <varname>trace_mode</varname>
605                 parameter</title>
606                 <programlisting format="linespecific">
607 ...
608 modparam("siptrace", "trace_on", 1)
609 modparam("siptrace", "trace_mode", 1)
610 ...
611 modparam("siptrace", "trace_mode", 3)
612 ...
613 </programlisting>
614                 </example>
615         </section>
616         <section id="siptrace.p.auth_key">
617                 <title><varname>auth_key</varname> (integer)</title>
618                 <para>
619 A string with an authorization key.
620 Supported on HEPv3 only.
621                 </para>
622                 <para>
623                 Default value is empty.
624                 </para>
625                 <example>
626                 <title>Set <varname>auth_key</varname>
627                 parameter</title>
628                 <programlisting format="linespecific">
629 ...
630 modparam("siptrace", "auth_key", "spoihepuirthpeuia")
631 ...
632 </programlisting>
633                 </example>
634         </section>
635         </section>
636
637         <section>
638         <title>Functions</title>
639         <section id="siptrace.f.sip_trace">
640                 <title>
641                 <function moreinfo="none">sip_trace([address][,correlation_id][,mode])</function>
642                 </title>
643                 <para>
644                 Store or forward the current processed SIP message/transaction/dialog in database.
645                 It is stored in the form prior applying changes made to it. Based on mode, one can trace
646                 the current message('m' - default), the current transaction('t') or the current dialog('d').
647                 </para>
648                 <para>Meaning of the parameters is as follows:</para>
649                 <itemizedlist>
650                 <listitem>
651                 <para><emphasis>address</emphasis> - The address in form of SIP URI
652                 where to send a duplicate of traced message. This parameter trumps
653                 duplicate_uri and allows tracing to more than one server.
654                 </para>
655                 </listitem>
656                 <listitem>
657                 <para><emphasis>correlation_id</emphasis> - A string with a correlation ID
658                 to be added to the HEP header when using HEPv3.
659                 It's possible to use PVs.
660                 </para>
661                 </listitem>
662                 <listitem>
663                 <para><emphasis>mode</emphasis> - SIP messages to be traced. One can trace the current message
664                 (function can be called on either a reply or a request), the current transaction(the route must
665                 belong to a request) or the current dialog(the message has to be an invite).
666                 </para>
667                 </listitem>
668                 </itemizedlist>
669                 <para>
670                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
671                 ONREPLY_ROUTE, BRANCH_ROUTE.
672                 </para>
673                 <emphasis>
674                         Default value is "NULL".
675                 </emphasis>
676                 <example>
677                 <title><function>sip_trace()</function> usage</title>
678                 <programlisting format="linespecific">
679 ...
680 sip_trace();
681 ...
682 sip_trace("sip:10.1.1.2:5085");
683 ...
684 sip_trace("sip:10.1.1.2:5085", "$ci-abc");
685 ...
686 /* trace current dialog; needs to be done on initial INVITE and dialog has to be loaded */
687 sip_trace("sip:10.1.1.2:5085", "$ci-abc", "d");
688 ...
689 </programlisting>
690                 </example>
691         </section>
692
693         <section id="siptrace.f.sip_trace_mode">
694                 <title>
695                 <function moreinfo="none">sip_trace_mode(tmode)</function>
696                 </title>
697                 <para>
698                         Set the tracing mode: message, transaction or dialog. Only the first
699                         character of the parameter matters: m or M for message; t or T for
700                         transaction; d or D for dialog.
701                 </para>
702                 <para>
703                         In message tracing mode only the current message is stored or mirrored.
704                         In transaction tracing mode, all the messages of the current transaction
705                         are stored or mirrored. In dialog tracing mode, all the messages of the
706                         current dialog are stored or mirrored.
707                 </para>
708                 <para>
709                 This function can be used in ANY_ROUTE.
710                 </para>
711                 <example>
712                 <title><function>sip_trace_mode()</function> usage</title>
713                 <programlisting format="linespecific">
714 ...
715 sip_trace_mode("t");
716 ...
717 </programlisting>
718                 </example>
719         </section>
720
721         <section id="siptrace.f.hlog">
722                 <title>
723                 <function moreinfo="none">hlog([correlation_id,] message)</function>
724                 </title>
725                 <para>
726                 Sends a log event as a HEP3 packet to the homer host configured in
727                 <emphasis>duplicate_uri</emphasis>.
728                 </para>
729                 <para>Meaning of the parameters is as follows:</para>
730                 <itemizedlist>
731                         <listitem>
732                         <para><emphasis>correlation_id</emphasis> (optional) - Homer correlation
733                         ID for this event. If this parameter is not set, the current message's
734                         call-id will be used. (This parameter may contain PVs)
735                         </para>
736                         </listitem>
737                         <listitem>
738                         <para><emphasis>message</emphasis> - The text to send to Homer as log
739                         event. (This parameter may contain PVs)
740                         </para>
741                         </listitem>
742                 </itemizedlist>
743                 <example>
744                 <title><function>hlog()</function> usage</title>
745                 <programlisting format="linespecific">
746 ...
747 hlog("[cfg:$cfg(line)] This is a log from kamailio to Homer");
748 ...
749 hlog("$hdr(P-MyID)", "Another one with a custom correlation ID");
750 ...
751 </programlisting>
752                 </example>
753         </section>
754
755         </section>
756
757     <section>
758         <title>RPC Commands</title>
759         <section id="siptrace.r.siptrace.status">
760                 <title>
761                 <function moreinfo="none">siptrace.status param</function>
762                 </title>
763                 <para>
764
765                 </para>
766                 <para>
767                 Name: <emphasis>siptrace.status</emphasis>
768                 </para>
769                 <para>Parameters: </para>
770                 <itemizedlist>
771                         <listitem><para>on or off: turns on/off SIP message tracing.
772                         Possible values are:</para>
773                         <itemizedlist>
774                                 <listitem><para>on</para></listitem>
775                                 <listitem><para>off</para></listitem>
776                         </itemizedlist>
777                         </listitem>
778                         <listitem><para><quote>check</quote> does not change
779                         siptrace status, just reports the current status.</para>
780                         </listitem>
781                 </itemizedlist>
782                 <para>
783                 RPC Command Format:
784                 </para>
785                 <programlisting  format="linespecific">
786 ...
787 &kamcmd; siptrace.status on
788 &kamcmd; siptrace.status off
789 &kamcmd; siptrace.status check
790 ...
791                 </programlisting>
792         </section>
793         </section><!-- RPC commands -->
794
795         <section>
796                 <title>Database setup</title>
797                 <para>
798                 Before running &kamailio; with siptrace, you have to setup the database
799                 tables where the module will store the data. For that, if the
800                 table were not created by the installation script or you choose
801                 to install everything by yourself you can use the siptrace-create.sql
802                 <acronym>SQL</acronym> script in the database directories in the
803                 kamailio/scripts folder as template.
804                 You can also find the complete database documentation on the
805                 project webpage, &kamailiodbdocslink;.
806                 </para>
807         </section>
808
809         <section>
810         <title>Known issues</title>
811         <para>
812         Stateless forwarded messages (forward()) are not logged if you set the
813         flag, use sip_trace() inside <emphasis>onsend_route</emphasis> block.
814         </para>
815         <para>
816         If dialog level tracing is used internally generated BYE transaction(in
817         case of internal timeouts) won't be traced. At the moment kamailio offers
818         no posibility to trace those messages.
819         </para>
820         <para>
821                 <emphasis>Trace_info</emphasis> xavp name is reserved by this module.
822                 Any use of xavp with this name will result in overlapping internal
823                 avp used by the module therefore causing unknown consequences.
824         </para>
825         <example>
826         <title>Send relayed ACK message</title>
827         <programlisting format="linespecific">
828 ...
829 onsend_route {
830     if (is_method("ACK")) {
831         sip_trace();
832     }
833 }
834 ...
835 </programlisting>
836         </example>
837         </section>
838
839 </chapter>
840