nsq: updated doc
[sip-router] / modules / nsq / doc / nsq_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 "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter xmlns:xi="http://www.w3.org/2001/XInclude">
13         <title>&adminguide;</title>
14
15
16         <section>
17                 <title>Overview</title>
18                 <para>The module provides an NSQ consumer for &kamailio; configuration file.
19                         You can read more about NSQ at <ulink url="http://nsq.io">nsq.io</ulink>.
20                 </para>
21                 <para>
22                         From a high-level perspective, the module may be used for:
23                         <itemizedlist>
24                                 <listitem>
25                                         <para>
26                                                 Provide a real-time integration into your program, instead of your database, so you can overlay additional logic in your preferred language while also utilizing a message bus
27                                         </para>
28                                 </listitem>
29                                 <listitem>
30                                         <para>
31                                                 Utilize messaging to have a distributed messaging layer, such that machines processing requests/responses/events can go up/down or share the workload and your Kamailio node will still be happy
32                                         </para>
33                                 </listitem>
34                         </itemizedlist>
35                 </para>
36
37
38                 <para>
39                         supported operations are:
40                         <itemizedlist>
41                                 <listitem>
42                                         <para>
43                                                 subscribe to a Topic and Channel
44                                         </para>
45                                 </listitem>
46                         </itemizedlist>
47                 </para>
48                 <para>
49                         The NSQ module also has support to publish updates to presence module through the nsq_pua_publish function
50                 </para>
51
52         </section>
53         <section>
54                 <title>How it works</title>
55                 <para>
56                         The module works with a main forked process that does the communication with NSQ for consuming messages. When it consumes a message it defers the process to a worker process so that it doesn't block this main process.
57                 </para>
58                 <section>
59                         <title>event routes</title>
60                         <para>
61                                 The worker process issues an event-route where we can act on the received payload. The name of the event-route is composed by values extracted from the payload.
62                         </para>
63                         <para>
64                                 NSQ module will try to execute the event route from most significant to less significant.
65                                 define the event route like event_route[nsq:consumer-event[-payload_key_value[-payload_subkey_value]]]
66                         </para>
67                         <para>
68                                 we can set the key/subkey pair on a subscription base. check the payload on subscribe.
69                         </para>
70                         <example>
71                                 <title>define the event route</title>
72 <programlisting format="linespecific">
73 ...
74 modparam("nsq", "consumer_event_key", "Event-Category")
75 modparam("nsq", "consumer_event_sub_key", "Event-Name")
76 ...
77
78 event_route[nsq:consumer-event-presence-update]
79 {
80         # presence is the value extracted from Event-Category field in json payload
81         # update is the value extracted from Event-Name field in json payload
82         xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{kznsqjson,From})");
83         ...
84 }
85
86 event_route[nsq:consumer-event-presence]
87 {
88         # presence is the value extracted from Event-Category field in json payload
89         xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From})");
90         ...
91 }
92
93 event_route[nsq:consumer-event-event-category-event-name]
94 {
95         # event-category is the name of the consumer_event_key parameter
96         # event-name is the name of the consumer_event_sub_key parameter
97         # this event route is executed if we can't find the previous
98         ...
99 }
100
101 event_route[nsq:consumer-event-event-category]
102 {
103         # event-category is the name of the consumer_event_key parameter
104         # this event route is executed if we can't find the previous
105         ...
106 }
107
108 event_route[nsq:consumer-event]
109 {
110         # this event route is executed if we can't find the previous
111 }
112
113 </programlisting>
114                         </example>
115                 </section>
116                 <section>
117                         <title>aknowledge messages</title>
118                         <para>
119                                 Consumed messages have the option of being acknowledge in two ways:
120                                 <itemizedlist>
121                                         <listitem>
122                                                 <para>
123                                                         immediately when received
124                                                 </para>
125                                         </listitem>
126                                         <listitem>
127                                                 <para>
128                                                         after processing by the worker
129                                                 </para>
130                                         </listitem>
131                                 </itemizedlist>
132
133                         </para>
134
135                 </section>
136         </section>
137
138         <section>
139                 <title>Dependencies</title>
140                 <section>
141                         <title>&kamailio; Modules</title>
142                         <para>
143                                 The following modules must be loaded before this module:
144                                 <itemizedlist>
145                                         <listitem>
146                                                 <para>
147                                                         <emphasis>none</emphasis>.
148                                                 </para>
149                                         </listitem>
150                                 </itemizedlist>
151                         </para>
152                 </section>
153                 <section>
154                         <title>External Libraries or Applications</title>
155                         <itemizedlist>
156                                 <listitem>
157                                         <para>
158                                                 <emphasis>libev</emphasis>.
159                                         </para>
160                                 </listitem>
161                                 <listitem>
162                                         <para>
163                                                 <emphasis>libjson</emphasis>.
164                                         </para>
165                                 </listitem>
166                                 <listitem>
167                                         <para>
168                                                 <emphasis>libevbuffsock</emphasis>.
169                                         </para>
170                                 </listitem>
171                                 <listitem>
172                                         <para>
173                                                 <emphasis>libnsq</emphasis>.
174                                         </para>
175                                 </listitem>
176                         </itemizedlist>
177
178                 </section>
179         </section>
180
181
182         <section>
183                 <title>Parameters</title>
184                 <section>
185                         <title>NSQ related</title>
186                         <section>
187                                 <title><varname>lookupd_address</varname>(str)</title>
188                                 <para>
189                                         The nsqlookupd address.
190                                 </para>
191                                 <para>
192                                         <emphasis>Default value is 127.0.0.1</emphasis>
193                                 </para>
194                                 <example>
195                                         <title>Set <varname>lookupd_address</varname> parameter</title>
196 <programlisting format="linespecific">
197 ...
198 modparam("nsq", "lookupd_address", "nsqlookupd.mydomain.com")
199 ...
200 </programlisting>
201                                 </example>
202                         </section>
203                         <section>
204                                 <title><varname>lookupd_port</varname>(int)</title>
205                                 <para>
206                                         The nsqlookupd TCP port.
207                                 </para>
208                                 <para>
209                                         <emphasis>Default value is 4161.</emphasis>
210                                 </para>
211                                 <example>
212                                         <title>Set <varname>lookupd_port</varname> parameter</title>
213 <programlisting format="linespecific">
214 ...
215 modparam("nsq", "lookupd_port", 4161)
216 ...
217                                         </programlisting>
218                                 </example>
219                         </section>
220
221                         <section>
222                                 <title><varname>nsqd_address</varname>(str)</title>
223                                 <para>
224                                         The nsqd address. You can specify connecting directly to nsqd instead of using nsqlookupd.
225                                 </para>
226                                 <para>
227                                         <emphasis>Default value is 127.0.0.1</emphasis>
228                                 </para>
229                                 <example>
230                                         <title>Set <varname>nsqd_address</varname> parameter</title>
231 <programlisting format="linespecific">
232 ...
233 modparam("nsq", "nsqd_address", "nsqd.mydomain.com")
234 ...
235 </programlisting>
236                                 </example>
237                         </section>
238                         <section>
239                                 <title><varname>nsqd_port</varname>(int)</title>
240                                 <para>
241                                         The nsqd TCP port.
242                                 </para>
243                                 <para>
244                                         <emphasis>Default value is 4150.</emphasis>
245                                 </para>
246                                 <example>
247                                         <title>Set <varname>nsqd_port</varname> parameter</title>
248 <programlisting format="linespecific">
249 ...
250 modparam("nsq", "nsqd_port", 4150)
251 ...
252 </programlisting>
253                                 </example>
254                         </section>
255
256                         <section>
257                                 <title><varname>consumer_use_nsqd</varname>(int)</title>
258                                 <para>
259                                         Set to 1 if you'd like to connect to nsqd instead of nsqlookupd.
260                                 </para>
261                                 <para>
262                                         <emphasis>Default value is 0.</emphasis>
263                                 </para>
264                                 <example>
265                                         <title>Set <varname>consumer_use_nsqd</varname> parameter</title>
266 <programlisting format="linespecific">
267 ...
268 modparam("nsq", "consumer_use_nsqd", 1)
269 ...
270 </programlisting>
271                                 </example>
272                         </section>
273
274                         <section>
275                                 <title><varname>consumer_event_key</varname>(str)</title>
276                                 <para>
277                                         The default name of the field in json payload to compose the event name 1st part
278                                 </para>
279                                 <para>
280                                         <emphasis>Default value is <quote>Event-Category</quote>.</emphasis>
281                                 </para>
282                                 <example>
283                                         <title>Set <varname>consumer_event_key</varname> parameter</title>
284 <programlisting format="linespecific">
285 ...
286 modparam("nsq", "consumer_event_key", "My-JSON-Field-Name")
287 ...
288 </programlisting>
289                                 </example>
290                         </section>
291
292                         <section>
293                                 <title><varname>consumer_event_sub_key</varname>(str)</title>
294                                 <para>
295                                         The default name of the field in json payload to compose the event name 2nd part
296                                 </para>
297                                 <para>
298                                         <emphasis>Default value is <quote>Event-Name</quote>.</emphasis>
299                                 </para>
300                                 <example>
301                                         <title>Set <varname>consumer_event_sub_key</varname> parameter</title>
302 <programlisting format="linespecific">
303 ...
304 modparam("nsq", "consumer_event_sub_key", "My-JSON-SubField-Name")
305 ...
306 </programlisting>
307                                 </example>
308                         </section>
309
310                         <section>
311                                 <title><varname>max_in_flight</varname>(int)</title>
312                                 <para>
313                                         The number of messages the consumer can receive before nsqd expects a response.
314                                 </para>
315                                 <para>
316                                         <emphasis>Default value is 1.</emphasis>
317                                 </para>
318                                 <example>
319                                         <title>Set <varname>max_in_flight</varname> parameter</title>
320 <programlisting format="linespecific">
321 ...
322 modparam("nsq", "max_in_flight", 2)
323 ...
324 </programlisting>
325                                 </example>
326                         </section>
327
328                         <section>
329                                 <title><varname>consumer_workers</varname>(int)</title>
330                                 <para>
331                                         Number of consumer connections to NSQ per topic_channel.
332                                 </para>
333                                 <para>
334                                         <emphasis>Default value is 4.</emphasis>
335                                 </para>
336                                 <example>
337                                         <title>Set <varname>consumer_workers</varname> parameter</title>
338 <programlisting format="linespecific">
339 ...
340 modparam("nsq", "consumer_workers", 2)
341 ...
342 </programlisting>
343                                 </example>
344                         </section>
345
346                         <section>
347                                 <title><varname>topic_channel</varname>(str)</title>
348                                 <para>
349                                         The NSQ Topic and Channel. Delimiter-separated by <quote>:</quote>. It be set multiple times to subscribe to multiple topics and channels. The value of consumer_workers is allocated per topic_channel.
350                                 </para>
351                                 <para>
352                                         <emphasis>Default value is <quote>Kamailio-Topic:Kamailio-Channel</quote>.</emphasis>
353                                 </para>
354                                 <example>
355                                         <title>Set <varname>topic_channel</varname> parameter</title>
356 <programlisting format="linespecific">
357 ...
358 modparam("nsq", "topic_channel", "My-NSQ-Topic:My-NSQ-Channel")
359 modparam("nsq", "topic_channel", "My-NSQ-Topic-2:My-NSQ-Channel-2")
360 ...
361                                         </programlisting>
362                                 </example>
363                         </section>
364
365                 </section>
366
367                 <section>
368                         <title>Presence Related</title>
369                         <section>
370                                 <title><varname>db_url</varname>(str)</title>
371                                 <para>
372                                         The database for the presentity table.
373                                 </para>
374                                 <para>If set, the nsq_pua_publish function will update the presentity status in the database.
375                                 </para>
376                                 <para>
377                                         <emphasis>Default value is <quote>NULL</quote>.</emphasis>
378                                 </para>
379                                 <example>
380                                         <title>Set <varname>db_url</varname> parameter</title>
381 <programlisting format="linespecific">
382 ...
383 modparam("nsq", "db_url", "&defaultdb;")
384 ...
385 </programlisting>
386                                 </example>
387                         </section>
388
389                         <section>
390                                 <title><varname>presentity_table</varname>(str)</title>
391                                 <para>
392                                         The name of the presentity table in the database.
393                                 </para>
394                                 <para>
395                                         <emphasis>Default value is <quote>presentity</quote>.</emphasis>
396                                 </para>
397                                 <example>
398                                         <title>Set <varname>presentity_table</varname> parameter</title>
399 <programlisting format="linespecific">
400 ...
401 modparam("nsq", "presentity_table", "my_presentity_table")
402 ...
403 </programlisting>
404                                 </example>
405                         </section>
406
407
408                 </section>
409
410
411
412
413
414         </section>
415         <section>
416                 <title>Functions</title>
417
418                 <section>
419                         <title>Presence Pelated</title>
420                         <section>
421                                 <title>
422                                         <function moreinfo="none">nsq_pua_publish(json_payload)</function>
423                                 </title>
424                                 <para>
425                                         The function build presentity state from json_payload and updates presentity table.
426                                 </para>
427                                 <para>
428                                         This function can be used from ANY ROUTE.
429                                 </para>
430
431                                 <example>
432                                         <title><function>nsq_pua_publish</function> usage</title>
433 <programlisting format="linespecific">
434 ...
435 event_route[nsq:consumer-event-presence-update]
436 {
437         xlog("L_INFO", "received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From})");
438         nsq_pua_publish($nsqE);
439         pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-Package})", 1);
440 }
441 ...
442 </programlisting>
443                                 </example>
444                         </section>
445
446
447                 </section>
448
449         </section>
450
451         <section>
452                 <title>Exported pseudo-variables</title>
453                 <itemizedlist>
454                         <listitem>
455                                 <para>
456                                         <emphasis>$nsqE</emphasis>
457                                         Contains the payload of a consumed message
458                                 </para>
459                         </listitem>
460                 </itemizedlist>
461         </section>
462
463         <section>
464                 <title>Transformations</title>
465                 <para>The prefix for nsq transformations is nsq.</para>
466                 <itemizedlist>
467                         <listitem><para>
468                                         <emphasis>json</emphasis>
469                                 </para>
470                                 <example>
471                                         <title><function>nsq.json</function> usage</title>
472 <programlisting format="linespecific">
473 ...
474 $var(Custom-Data) = $(nsqE{nsq.json,Custom-Data});
475 if($var(Custom-Data) != $null) {
476         xlog("L_INFO", "$ci|log|custom data: $var(Custom-Data)");
477 }
478 ...
479 </programlisting>
480                                 </example>
481
482                         </listitem>
483
484                 </itemizedlist>
485         </section>
486
487
488 </chapter>
489