Debian Codegraph @

src/modules/acc_json/README

raw
1 ACC_JSON Module
2
3 Julien Chavanton
4
5 <[email protected]>
6
7 Julien Chavanton
8
9 flowroute.com
10 <[email protected]>
11
12 Edited by
13
14 Julien Chavanton
15
16 flowroute.com
17 <[email protected]>
18
19 Copyright © 2018 Flowroute.com
20 __________________________________________________________________
21
22 Table of Contents
23
24 1. Admin Guide
25
26 1. Overview
27 2. Dependencies
28
29 2.1. Kamailio Modules
30 2.2. External Libraries or Applications
31
32 3. Parameters
33
34 3.1. acc_flag (integer)
35 3.2. acc_missed_flag (integer)
36 3.3. acc_extra (string)
37 3.4. acc_pre_encoded_prefix (string)
38 3.5. acc_time_mode (integer)
39 3.6. acc_time_format (str)
40 3.7. acc_output_mqueue (integer)
41 3.8. acc_output_syslog (integer)
42 3.9. acc_log_facility (integer)
43 3.10. acc_log_level (integer)
44 3.11. cdr_enable (int)
45 3.12. cdr_skip (string)
46 3.13. cdr_extra (str)
47 3.14. cdr_pre_encoded_prefix (string)
48 3.15. cdr_expired_dlg_enable (str)
49 3.16. cdr_output_mqueue (integer)
50 3.17. cdr_output_syslog (integer)
51 3.18. cdr_log_facility (integer)
52 3.19. cdr_log_level (integer)
53
54 List of Examples
55
56 1.1. acc_flag example
57 1.2. acc_missed_flag example
58 1.3. acc_extra example
59 1.4. acc_pre_encoded_prefix example
60 1.5. acc_time_mode example
61 1.6. acc_time_format example
62 1.7. acc_output_mqueue usage example
63 1.8. acc_output_syslog example
64 1.9. acc_log_facility example
65 1.10. acc_log_level example
66 1.11. cdr_enable example
67 1.12. cdr_skip example
68 1.13. cdr_extra example
69 1.14. cdr_pre_encoded_prefix example
70 1.15. cdr_expired_dlg_enable example
71 1.16. cdr_output_mqueue usage example
72 1.17. cdr_log_facility example
73 1.18. cdr_log_level example
74
75 Chapter 1. Admin Guide
76
77 Table of Contents
78
79 1. Overview
80 2. Dependencies
81
82 2.1. Kamailio Modules
83 2.2. External Libraries or Applications
84
85 3. Parameters
86
87 3.1. acc_flag (integer)
88 3.2. acc_missed_flag (integer)
89 3.3. acc_extra (string)
90 3.4. acc_pre_encoded_prefix (string)
91 3.5. acc_time_mode (integer)
92 3.6. acc_time_format (str)
93 3.7. acc_output_mqueue (integer)
94 3.8. acc_output_syslog (integer)
95 3.9. acc_log_facility (integer)
96 3.10. acc_log_level (integer)
97 3.11. cdr_enable (int)
98 3.12. cdr_skip (string)
99 3.13. cdr_extra (str)
100 3.14. cdr_pre_encoded_prefix (string)
101 3.15. cdr_expired_dlg_enable (str)
102 3.16. cdr_output_mqueue (integer)
103 3.17. cdr_output_syslog (integer)
104 3.18. cdr_log_facility (integer)
105 3.19. cdr_log_level (integer)
106
107 1. Overview
108
109 ACC_JSON module is used to account transaction information in a JSON
110 dictionary. It binds to ACC module API and uses the same accounting
111 mechanisms as for other backends.
112
113 It can output the JSON dictionary to MQUEUE or SYSLOG (even if Kamailio
114 is not using syslog)
115
116 2. Dependencies
117
118 2.1. Kamailio Modules
119 2.2. External Libraries or Applications
120
121 2.1. Kamailio Modules
122
123 The module depends on the following modules (in other words the listed
124 modules must be loaded before this module):
125 * acc - accounting module
126 * mqueue - mqueue module (optional)
127
128 2.2. External Libraries or Applications
129
130 The following libraries or applications must be installed before
131 running Kamailio with this module loaded:
132 * jansson http://www.digip.org/jansson/
133 Jansson is a C library for encoding, decoding and manipulating JSON
134 data.
135
136 3. Parameters
137
138 3.1. acc_flag (integer)
139 3.2. acc_missed_flag (integer)
140 3.3. acc_extra (string)
141 3.4. acc_pre_encoded_prefix (string)
142 3.5. acc_time_mode (integer)
143 3.6. acc_time_format (str)
144 3.7. acc_output_mqueue (integer)
145 3.8. acc_output_syslog (integer)
146 3.9. acc_log_facility (integer)
147 3.10. acc_log_level (integer)
148 3.11. cdr_enable (int)
149 3.12. cdr_skip (string)
150 3.13. cdr_extra (str)
151 3.14. cdr_pre_encoded_prefix (string)
152 3.15. cdr_expired_dlg_enable (str)
153 3.16. cdr_output_mqueue (integer)
154 3.17. cdr_output_syslog (integer)
155 3.18. cdr_log_facility (integer)
156 3.19. cdr_log_level (integer)
157
158 3.1. acc_flag (integer)
159
160 Request flag which needs to be set to account a transaction in
161 acc_json. See acc_output_mqueue and acc_output_syslog
162
163 Default value is not-set (no flag).
164
165 Example 1.1. acc_flag example
166 ...
167 modparam("acc_json", "acc_flag", 2)
168 ...
169
170 3.2. acc_missed_flag (integer)
171
172 Request flag which needs to be set to account missed calls in acc_json.
173 See acc_output_mqueue and acc_output_syslog
174
175 Default value is not-set (no flag).
176
177 Example 1.2. acc_missed_flag example
178 ...
179 modparam("acc_json", "acc_missed_flag", 3)
180 ...
181
182 3.3. acc_extra (string)
183
184 Extra values to be added to the json dictionary.
185
186 Default value is NULL.
187
188 Example 1.3. acc_extra example
189 ...
190 modparam("acc_json", "acc_extra", "via=$hdr(Via[*]); email=$avp(s:email)")
191 ...
192
193 3.4. acc_pre_encoded_prefix (string)
194
195 Prefix to identify values that will be considered to be already json
196 encoded.
197
198 Default value is NULL.
199
200 Example 1.4. acc_pre_encoded_prefix example
201 ...
202 modparam("acc_json", "acc_extra", "json_data=$avp(json_data);")
203 modparam("acc_json", "acc_pre_encoded_prefix", "json_")
204 ...
205 $avp(json_data) = '{"b":2, "c":3}';
206 ...
207
208 3.5. acc_time_mode (integer)
209
210 Store additional value related to the time of event.
211
212 Values can be:
213 * 0 - (default), save only unix timestamp for syslog and datetime for
214 database.
215 * 1 - save seconds in time_attr and microseconds in time_exten.
216 * 2 - save seconds.milliseconds in time_attr.
217 * 3 - save formatted time according to time_format parameter, using
218 the output of localtime(). Used for cdr entries too.
219 * 4 - save formatted time according to time_format parameter, using
220 the output of gmtime(). Used for cdr entries too.
221
222 Example 1.5. acc_time_mode example
223 ...
224 modparam("acc_json", "acc_time_mode", 1)
225 ...
226
227 3.6. acc_time_format (str)
228
229 Specify the format to print the time for time_mode 3 or 4.
230
231 Default value is %Y-%m-%d %H:%M:%S".
232
233 Example 1.6. acc_time_format example
234 ...
235 modparam("acc_json", "acc_time_format", "%Y/%m/%d %H:%M:%S")
236 ...
237
238 3.7. acc_output_mqueue (integer)
239
240 Requires the mqueue module. The acc module will queue json acc events
241 in the specified mqueue. Using a rtimer module exec you can access the
242 queue and process them.
243
244 You can also fetch the acc events using mqueue.fetch over JSON-RPC.
245
246 Default value is not-set mqueue will not be required.
247
248 Example 1.7. acc_output_mqueue usage example
249 ...
250 # example using json_mqueue/http_client to publish to NSQD
251 max_while_loops=100000
252 modparam("mqueue", "mqueue", "name=acc_events;size=100000")
253 modparam("acc_json", "acc_output_mqueue", "acc_events")
254 modparam("acc_json", "acc_flag", 2)
255 modparam("acc_json", "acc_extra", "caller_ip_port=$avp(caller_ip_port);")
256 modparam("rtimer", "timer", "name=nsqt;interval=1;mode=1;")
257 modparam("rtimer", "exec", "timer=nsqt;route=RUN_CDR_PUBLISH")
258 modparam("http_client", "keep_connections", 1)
259 modparam("http_client", "httpcon", "nsqd=>http://localhost:4151/pub?topic=acc")
260
261 route[RUN_ACC_PUBLISH] {
262 $var(count) = 0;
263 while (mq_fetch("acc_events")) {
264 $var(q_size) = mq_size("acc_events");
265 $var(count) = $var(count) + 1;
266 xinfo("[RUN_ACC_PUBLISH][$var(q_size)][$var(count)][$mqk(acc_events)][$mqv
267 (acc_events)]\n");
268 $var(res) = http_connect_raw("nsqd", "", "application/json", $mqv(acc_even
269 ts), "$var(nsq_res)");
270 if ($var(res) < 0) {
271 xerr("[RUN_ACC_PUBLISH][$var(res)] http_connect_raw: timeout or error !
272 \n");
273 mq_add("acc_events", "acc_key", "$mqv(acc_events)");
274 } else if ($var(res) < 200 || $var(res) > 299) {
275 xerr("[RUN_ACC_PUBLISH][$var(res)] http unexpected response code !\n");
276 mq_add("acc_dead_letter_queue", "acc_key", "$mqv(acc_events)");
277 return;
278 }
279 }
280 if ($var(count) > 0 ) {
281 xinfo("[RUN_CDR_PUBLISH]done count[$var(count)]\n");
282 }
283 }
284 ...
285
286 3.8. acc_output_syslog (integer)
287
288 Control if the output of acc json should be sent to syslog. This is not
289 dependent on Kamailio global logging settings, we can use syslog even
290 if Kamailio is not daemonized and/or logging is done to sdtout stderr.
291
292 Default value is not-set (no flag).
293
294 Example 1.8. acc_output_syslog example
295 ...
296 modparam("acc_json", "acc_output_syslog", 1)
297 modparam("acc_json", "acc_log_level", 2)
298 modparam("acc_json", "acc_log_facility", "LOG_DAEMON")
299 ...
300
301 3.9. acc_log_facility (integer)
302
303 Log facility to which accounting messages are issued to syslog. This
304 allows to easily separate the accounting specific logging from the
305 other log messages.
306
307 Default value is LOG_DAEMON.
308
309 Example 1.9. acc_log_facility example
310 ...
311 modparam("acc_json", "acc_log_facility", "LOG_LOCAL0")
312
313 # modify you syslog/rsyslog config
314 # /etc/rsyslog.d/default.conf
315 # remove local0 from default log file
316 # *.*;local0,auth,authpriv.none /var/log/syslog
317 # add local0 to another log file
318 # local0.* /var/log/json_acc.log
319 ...
320
321 3.10. acc_log_level (integer)
322
323 Log level at which accounting messages are issued to syslog.
324
325 Default value is 1 (L_NOTICE).
326
327 Example 1.10. acc_log_level example
328 ...
329 modparam("acc_json", "acc_log_level", 2) # Set acc_log_level to 2 (L_INFO)
330 ...
331
332 3.11. cdr_enable (int)
333
334 Enable CDR reporting - one record per call is reported, relying on
335 dialog module.
336
337 The value can be:
338 * 0 - off (default).
339 1 - on.
340
341 Example 1.11. cdr_enable example
342 ...
343 modparam("acc_json", "cdr_enable", 1)
344 ...
345
346 3.12. cdr_skip (string)
347
348 Skip cdr generation for dialogs with this dlg_var set.
349
350 Default value is NULL.
351
352 Example 1.12. cdr_skip example
353 ...
354 modparam("acc_json", "cdr_skip", "nocdr")
355 ...
356
357 3.13. cdr_extra (str)
358
359 Set of pseudo-variables defining custom CDR fields.
360
361 Default value is NULL.
362
363 Example 1.13. cdr_extra example
364 ...
365 modparam("acc_json", "cdr_extra", "ci=$dlg_var(call_id);ft=$dlg_var(from_tag)")
366 ...
367
368 3.14. cdr_pre_encoded_prefix (string)
369
370 Prefix to identify values that will be considered to be already json
371 encoded.
372
373 Default value is NULL.
374
375 Example 1.14. cdr_pre_encoded_prefix example
376 ...
377 modparam("acc_json", "cdr_extra", "json_data=$avp(json_data);")
378 modparam("acc_json", "cdr_pre_encoded_prefix", "json_")
379 ...
380 $avp(json_data) = '{"b":2, "c":3}';
381 ...
382
383 3.15. cdr_expired_dlg_enable (str)
384
385 Should CDR-based logging be enabled in case of expired dialogs?
386
387 0 - off (default). 1 - on.
388
389 Example 1.15. cdr_expired_dlg_enable example
390 ...
391 modparam("acc_json", "cdr_expired_dlg_enable", 1)
392 ...
393
394 3.16. cdr_output_mqueue (integer)
395
396 Requires the mqueue module. The acc module will queue json cdr events
397 in the specified mqueue. Using a rtimer module exec you can access the
398 queue and process them.
399
400 You can also fetch the cdr events using mqueue.fetch over JSON-RPC.
401
402 Default value is not-set mqueue will not be required.
403
404 Example 1.16. cdr_output_mqueue usage example
405 ...
406 # example using json_mqueue/http_client to publish to NSQD
407 modparam("mqueue", "mqueue", "name=cdr_events;size=100000")
408 modparam("acc_json", "cdr_enable", 1)
409 modparam("acc_json", "cdr_output_mqueue", "cdr_events")
410 modparam("acc_json", "cdr_extra", "ci=$dlg_var(call_id)")
411 modparam("rtimer", "timer", "name=nsqt;interval=1;mode=1;")
412 modparam("rtimer", "exec", "timer=nsqt;route=RUN_CDR_PUBLISH")
413 modparam("http_client", "keep_connections", 1)
414 modparam("http_client", "httpcon", "nsqd=>http://localhost:4151/pub?topic=acc")
415
416 route[RUN_CDR_PUBLISH] {
417 $var(count) = 0;
418 while (mq_fetch("cdr_events")) {
419 $var(q_size) = mq_size("cdr_events");
420 $var(count) = $var(count) + 1;
421 xinfo("[RUN_CDR_PUBLISH][$var(q_size)][$var(count)][$mqk(cdr_events)][$mqv
422 (cdr_events)]\n");
423 $var(res) = http_connect_raw("nsqd", "", "application/json", $mqv(cdr_even
424 ts), "$var(nsq_res)");
425 if ($var(res) < 0) {
426 xerr("[RUN_CDR_PUBLISH][$var(res)] http_connect_raw: timeout or error !
427 \n");
428 mq_add("cdr_events", "cdr_key", "$mqv(cdr_events)");
429 } else if ($var(res) < 200 || $var(res) > 299) {
430 xerr("[RUN_CDR_PUBLISH][$var(res)] http unexpected response code !\n");
431 mq_add("cdr_dead_letter_queue", "cdr_key", "$mqv(cdr_events)");
432 return;
433 }
434 }
435 if ($var(count) > 0 ) {
436 xinfo("[RUN_CDR_PUBLISH]done count[$var(count)]\n");
437 }
438 }
439 ...
440
441 3.17. cdr_output_syslog (integer)
442
443 The acc module will log json cdr events to syslog.
444
445 3.18. cdr_log_facility (integer)
446
447 Log facility to which accounting messages are issued to syslog. This
448 allows to easily separate the accounting specific logging from the
449 other log messages.
450
451 Default value is LOG_DAEMON.
452
453 Example 1.17. cdr_log_facility example
454 ...
455 modparam("acc_json", "cdr_log_facility", "LOG_LOCAL0")
456
457 # modify you syslog/rsyslog config
458 # /etc/rsyslog.d/default.conf
459 # remove local0 from default log file
460 # *.*;local0,auth,authpriv.none /var/log/syslog
461 # add local0 to another log file
462 # local0.* /var/log/json_cdr.log
463 ...
464
465 3.19. cdr_log_level (integer)
466
467 Log level at which accounting messages are issued to syslog.
468
469 Default value is 1 (L_NOTICE).
470
471 Example 1.18. cdr_log_level example
472 ...
473 modparam("acc_json", "cdr_log_level", 2) # Set cdr_log_level to 2 (L_INFO)
474 ...