Browse code

modules: readme files regenerated - xhttp_prom ... [skip ci]

Kamailio Dev authored on 10/08/2020 21:16:12
Showing 1 changed files
... ...
@@ -32,8 +32,10 @@ Javier Gallart
32 32
               3.1. xhttp_prom_buf_size (integer)
33 33
               3.2. xhttp_prom_timeout (integer)
34 34
               3.3. xhttp_prom_stats (str)
35
-              3.4. prom_counter (str)
36
-              3.5. prom_gauge (str)
35
+              3.4. xhttp_prom_beginning (str)
36
+              3.5. prom_counter (str)
37
+              3.6. prom_gauge (str)
38
+              3.7. prom_histogram (str)
37 39
 
38 40
         4. Functions
39 41
 
... ...
@@ -41,8 +43,9 @@ Javier Gallart
41 43
               4.2. prom_gauge_reset(name, l0, l1, l2)
42 44
               4.3. prom_counter_inc(name, number, l0, l1, l2)
43 45
               4.4. prom_gauge_set(name, number, l0, l1, l2)
44
-              4.5. prom_dispatch()
45
-              4.6. prom_check_uri()
46
+              4.5. prom_histogram_observe(name, number, l0, l1, l2)
47
+              4.6. prom_dispatch()
48
+              4.7. prom_check_uri()
46 49
 
47 50
         5. RPC Commands
48 51
 
... ...
@@ -50,29 +53,35 @@ Javier Gallart
50 53
               5.2. xhttp_prom.counter_inc
51 54
               5.3. xhttp_prom.gauge_reset
52 55
               5.4. xhttp_prom.gauge_set
53
-              5.5. xhttp_prom.metric_list_print
56
+              5.5. xhttp_prom.histogram_observe
57
+              5.6. xhttp_prom.metric_list_print
54 58
 
55 59
    List of Examples
56 60
 
57 61
    1.1. Set xhttp_prom_buf_size parameter
58 62
    1.2. Set xhttp_prom_timeout parameter
59 63
    1.3. Set xhttp_prom_stats parameter
60
-   1.4. prom_counter label example
61
-   1.5. Set prom_counter parameter
62
-   1.6. prom_gauge label example
63
-   1.7. Set prom_gauge parameter
64
-   1.8. prom_counter_reset usage
65
-   1.9. prom_gauge_reset usage
66
-   1.10. prom_counter_inc usage
67
-   1.11. prom_gauge_set usage
68
-   1.12. prom_dispatch usage
69
-   1.13. prom_dispatch usage (more complete)
70
-   1.14. prom_check_uri usage
71
-   1.15. xhttp_prom.counter_reset usage
72
-   1.16. xhttp_prom.counter_inc usage
73
-   1.17. xhttp_prom.gauge_reset usage
74
-   1.18. xhttp_prom.gauge_set usage
75
-   1.19. xhttp_prom.metric_list_print usage
64
+   1.4. Set xhttp_prom_beginning parameter
65
+   1.5. prom_counter label example
66
+   1.6. Set prom_counter parameter
67
+   1.7. prom_gauge label example
68
+   1.8. Set prom_gauge parameter
69
+   1.9. prom_histogram label example
70
+   1.10. Set prom_histogram parameter
71
+   1.11. prom_counter_reset usage
72
+   1.12. prom_gauge_reset usage
73
+   1.13. prom_counter_inc usage
74
+   1.14. prom_gauge_set usage
75
+   1.15. prom_histogram_observe usage
76
+   1.16. prom_dispatch usage
77
+   1.17. prom_dispatch usage (more complete)
78
+   1.18. prom_check_uri usage
79
+   1.19. xhttp_prom.counter_reset usage
80
+   1.20. xhttp_prom.counter_inc usage
81
+   1.21. xhttp_prom.gauge_reset usage
82
+   1.22. xhttp_prom.gauge_set usage
83
+   1.23. xhttp_prom.histogram_observe usage
84
+   1.24. xhttp_prom.metric_list_print usage
76 85
 
77 86
 Chapter 1. Admin Guide
78 87
 
... ...
@@ -89,8 +98,10 @@ Chapter 1. Admin Guide
89 98
         3.1. xhttp_prom_buf_size (integer)
90 99
         3.2. xhttp_prom_timeout (integer)
91 100
         3.3. xhttp_prom_stats (str)
92
-        3.4. prom_counter (str)
93
-        3.5. prom_gauge (str)
101
+        3.4. xhttp_prom_beginning (str)
102
+        3.5. prom_counter (str)
103
+        3.6. prom_gauge (str)
104
+        3.7. prom_histogram (str)
94 105
 
95 106
    4. Functions
96 107
 
... ...
@@ -98,8 +109,9 @@ Chapter 1. Admin Guide
98 109
         4.2. prom_gauge_reset(name, l0, l1, l2)
99 110
         4.3. prom_counter_inc(name, number, l0, l1, l2)
100 111
         4.4. prom_gauge_set(name, number, l0, l1, l2)
101
-        4.5. prom_dispatch()
102
-        4.6. prom_check_uri()
112
+        4.5. prom_histogram_observe(name, number, l0, l1, l2)
113
+        4.6. prom_dispatch()
114
+        4.7. prom_check_uri()
103 115
 
104 116
    5. RPC Commands
105 117
 
... ...
@@ -107,7 +119,8 @@ Chapter 1. Admin Guide
107 119
         5.2. xhttp_prom.counter_inc
108 120
         5.3. xhttp_prom.gauge_reset
109 121
         5.4. xhttp_prom.gauge_set
110
-        5.5. xhttp_prom.metric_list_print
122
+        5.5. xhttp_prom.histogram_observe
123
+        5.6. xhttp_prom.metric_list_print
111 124
 
112 125
 1. Overview
113 126
 
... ...
@@ -117,7 +130,8 @@ Chapter 1. Admin Guide
117 130
    It answers Prometheus pull requests (HTTP requests to /metrics URL).
118 131
 
119 132
    The module generates metrics based on Kamailio statistics, and also the
120
-   user can create his own metrics (currently counters and gauges).
133
+   user can create his own metrics (currently counters, gauges and
134
+   histograms).
121 135
 
122 136
    The xHTTP_PROM module uses the xHTTP module to handle HTTP requests.
123 137
    Read the documentation of the xHTTP module for more details.
... ...
@@ -155,8 +169,10 @@ Chapter 1. Admin Guide
155 169
    3.1. xhttp_prom_buf_size (integer)
156 170
    3.2. xhttp_prom_timeout (integer)
157 171
    3.3. xhttp_prom_stats (str)
158
-   3.4. prom_counter (str)
159
-   3.5. prom_gauge (str)
172
+   3.4. xhttp_prom_beginning (str)
173
+   3.5. prom_counter (str)
174
+   3.6. prom_gauge (str)
175
+   3.7. prom_histogram (str)
160 176
 
161 177
 3.1. xhttp_prom_buf_size (integer)
162 178
 
... ...
@@ -176,6 +192,8 @@ modparam("xhttp_prom", "xhttp_prom_buf_size", 1024)
176 192
    Specifies a timeout in minutes. A metric not used during this timeout
177 193
    is automatically deleted. Listing metrics does not count as using them.
178 194
 
195
+   If set to 0 timeout is disabled. Negative values are not allowed.
196
+
179 197
    Default value is 60 minutes.
180 198
 
181 199
    Example 1.2. Set xhttp_prom_timeout parameter
... ...
@@ -195,6 +213,11 @@ modparam("xhttp_prom", "xhttp_prom_timeout", 600)
195 213
 
196 214
    Default value is "", meaning do not display any Kamailio statistics.
197 215
 
216
+   IMPORTANT: Kamailio internal statistics are parsed to convert - into _,
217
+   so they accomplish with Prometheus guidelines for metric names.
218
+   https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels
219
+   User generated statistics and label names are not parsed.
220
+
198 221
    Example 1.3. Set xhttp_prom_stats parameter
199 222
 ...
200 223
 # show all kamailio statistics.
... ...
@@ -210,7 +233,26 @@ modparam("xhttp_prom", "xhttp_prom_stats", "200_replies")
210 233
 modparam("xhttp_prom", "xhttp_prom_stats", "")
211 234
 ...
212 235
 
213
-3.4. prom_counter (str)
236
+3.4. xhttp_prom_beginning (str)
237
+
238
+   Specifies beginning of string the metrics are build with.
239
+
240
+   It defaults to "kamailio_", so if not specified every metric will start
241
+   with "kamailio_".
242
+
243
+   Void string "" is also allowed, meaning no prefix string for every
244
+   metric name.
245
+
246
+   Example 1.4. Set xhttp_prom_beginning parameter
247
+...
248
+# All metrics will start with "my_metric_".
249
+modparam("xhttp_prom", "xhttp_prom_beginning", "my_metric_")
250
+
251
+# No string at the beginning.
252
+modparam("xhttp_prom", "xhttp_prom_beginning", "");
253
+...
254
+
255
+3.5. prom_counter (str)
214 256
 
215 257
    Create a counter metric.
216 258
 
... ...
@@ -226,13 +268,13 @@ modparam("xhttp_prom", "xhttp_prom_stats", "")
226 268
        parameter at most allowed in counters. Each label name is separated
227 269
        by : without spaces. At most only three label names allowed in each
228 270
        label parameter.
229
-       Example 1.4. prom_counter label example
271
+       Example 1.5. prom_counter label example
230 272
 # Create two labels called method and handler
231 273
 label = method:handler
232 274
 This would generate  {method="whatever", handler="whatever2"} when building
233 275
 the metric.
234 276
 
235
-   Example 1.5. Set prom_counter parameter
277
+   Example 1.6. Set prom_counter parameter
236 278
 ...
237 279
 
238 280
 # Create cnt_first counter with no labels.
... ...
@@ -250,7 +292,7 @@ using it by prom_counter_inc or prom_counter_reset functions.
250 292
 
251 293
 ...
252 294
 
253
-3.5. prom_gauge (str)
295
+3.6. prom_gauge (str)
254 296
 
255 297
    Create a gauge metric.
256 298
 
... ...
@@ -266,13 +308,13 @@ using it by prom_counter_inc or prom_counter_reset functions.
266 308
        parameter at most allowed in gauges. Each label name is separated
267 309
        by : without spaces. At most only three label names allowed inside
268 310
        each label parameter.
269
-       Example 1.6. prom_gauge label example
311
+       Example 1.7. prom_gauge label example
270 312
 # Create two labels called method and handler
271 313
 label = method:handler
272 314
 This would generate  {method="whatever", handler="whatever2"} when building
273 315
 the metric.
274 316
 
275
-   Example 1.7. Set prom_gauge parameter
317
+   Example 1.8. Set prom_gauge parameter
276 318
 ...
277 319
 
278 320
 # Create gg_first gauge with no labels
... ...
@@ -287,14 +329,67 @@ modparam("xhttp_prom", "prom_gauge", "name=gg_third; label=method:handler;");
287 329
 
288 330
 ...
289 331
 
332
+3.7. prom_histogram (str)
333
+
334
+   Create a histogram metric.
335
+
336
+   This function declares a histogram but the actual histogram is only
337
+   created when observing it.
338
+
339
+   It takes a list of attribute=value separated by semicolon, the
340
+   attributes can be name, label and buckets.
341
+     * name - name of the histogram. This attribute is mandatory. It is
342
+       used to generate the metric name. Each name is unique, no metric
343
+       shall repeat a name.
344
+     * label - names of labels in the histogram. Optional. Only one label
345
+       parameter at most allowed in histograms. Each label name is
346
+       separated by : without spaces. At most only three label names
347
+       allowed in each label parameter.
348
+       Example 1.9. prom_histogram label example
349
+# Create two labels called method and handler
350
+label = method:handler
351
+This would generate  {method="whatever", handler="whatever2"} when building
352
+the metric.
353
+     * buckets - specifies upper bounds for buckets in the histogram. This
354
+       attribute is optional.
355
+       Bucket values are separated by ":". Each value has to be a number.
356
+       "+Inf" upper bucket is always automatically included.
357
+       At least one bucket value is needed (other than +Inf).
358
+       Every bucket value has to increase in the list.
359
+       If no buckets specified, default bucket list is set to these
360
+       values:
361
+       [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
362
+
363
+   Example 1.10. Set prom_histogram parameter
364
+...
365
+
366
+# Create my_histo histogram with no labels and default buckets.
367
+modparam("xhttp_prom", "prom_histogram", "name=my_histo;");
368
+
369
+# Create second_histo histogram with one label and default buckets.
370
+# modparam("xhttp_prom", "prom_histogram", "name=second_histo; label=my_lbl");
371
+
372
+# Create a histogram with no labels and buckets 3.1, 5, 6.5
373
+modparam("xhttp_prom", "prom_histogram", "name=histo_third; buckets=3.1:5:6.5");
374
+
375
+# Create a histogram with a label and buckets 3.1, 5, 6.5
376
+modparam("xhttp_prom", "prom_histogram", "name=histo_fourth; label=lbl; buckets=
377
+3.1:5:6.5");
378
+
379
+These lines declare the histogram but the actual metric will be created when
380
+using it by prom_histogram_observe function.
381
+
382
+...
383
+
290 384
 4. Functions
291 385
 
292 386
    4.1. prom_counter_reset(name, l0, l1, l2)
293 387
    4.2. prom_gauge_reset(name, l0, l1, l2)
294 388
    4.3. prom_counter_inc(name, number, l0, l1, l2)
295 389
    4.4. prom_gauge_set(name, number, l0, l1, l2)
296
-   4.5. prom_dispatch()
297
-   4.6. prom_check_uri()
390
+   4.5. prom_histogram_observe(name, number, l0, l1, l2)
391
+   4.6. prom_dispatch()
392
+   4.7. prom_check_uri()
298 393
 
299 394
 4.1.  prom_counter_reset(name, l0, l1, l2)
300 395
 
... ...
@@ -311,7 +406,7 @@ modparam("xhttp_prom", "prom_gauge", "name=gg_third; label=method:handler;");
311 406
    Available via KEMI framework as counter_reset_l0, counter_reset_l1,
312 407
    counter_reset_l2 and counter_reset_l3.
313 408
 
314
-   Example 1.8. prom_counter_reset usage
409
+   Example 1.11. prom_counter_reset usage
315 410
 ...
316 411
 # Definition of counter with prom_counter with labels method and IP
317 412
 modparam("xhttp_prom", "prom_counter", "name=cnt01; label=method:IP;");
... ...
@@ -339,7 +434,7 @@ kamailio_cnt01 {method="push", IP="192.168.0.1"} 0 1234567890
339 434
    Available via KEMI framework as gauge_reset_l0, gauge_reset_l1,
340 435
    gauge_reset_l2 and gauge_reset_l3.
341 436
 
342
-   Example 1.9. prom_gauge_reset usage
437
+   Example 1.12. prom_gauge_reset usage
343 438
 ...
344 439
 # Definition of gauge with prom_gauge with labels method and IP
345 440
 modparam("xhttp_prom", "prom_gauge", "name=cnt01; label=method:IP;");
... ...
@@ -369,7 +464,7 @@ kamailio_cnt01 {method="push", IP="192.168.0.1"} 0 1234567890
369 464
    Available via KEMI framework as counter_inc_l0, counter_inc_l1,
370 465
    counter_inc_l2 and counter_inc_l3.
371 466
 
372
-   Example 1.10. prom_counter_inc usage
467
+   Example 1.13. prom_counter_inc usage
373 468
 ...
374 469
 # Definition of cnt01 counter with no labels.
375 470
 modparam("xhttp_prom", "prom_counter", "name=cnt01;");
... ...
@@ -406,7 +501,7 @@ kamailio_cnt02 {method="push", IP="192.168.0.1"} 15 1234567890
406 501
    Available via KEMI framework as gauge_set_l0, gauge_set_l1,
407 502
    gauge_set_l2 and gauge_set_l3.
408 503
 
409
-   Example 1.11. prom_gauge_set usage
504
+   Example 1.14. prom_gauge_set usage
410 505
 ...
411 506
 # Definition of gg01 gauge with no labels.
412 507
 modparam("xhttp_prom", "prom_gauge", "name=gg01;");
... ...
@@ -426,13 +521,57 @@ prom_gauge_set("gg02", "2.8", "push", "192.168.0.1");
426 521
 kamailio_gg02 {method="push", IP="192.168.0.1"} 2.8 1234567890
427 522
 ...
428 523
 
429
-4.5.  prom_dispatch()
524
+4.5.  prom_histogram_observe(name, number, l0, l1, l2)
525
+
526
+   Get a histogram identified by its name and labels and observe a value
527
+   in it. If histogram does not exist it creates the histogram and
528
+   accumulate the value in its buckets, counter and sum.
529
+
530
+   Name is mandatory, number is mandatory. Number is a string that will be
531
+   parsed as a float. l0, l1, l2 are values of labels and are optional.
532
+
533
+   name value and number of labels have to match a previous histogram
534
+   definition with prom_histogram.
535
+
536
+   This function accepts pseudovariables on its parameters.
537
+
538
+   Available via KEMI framework as histogram_observe_l0,
539
+   histogram_observe_l1, histogram_observe_l2 and histogram_observe_l3.
540
+
541
+   Example 1.15. prom_histogram_observe usage
542
+...
543
+# Definition of hist01 histogram with no labels and default buckets.
544
+modparam("xhttp_prom", "prom_histogram", "name=hist01;");
545
+...
546
+# Observe -12.5 value in hist01 histogram (with no labels). If histogram does no
547
+t exist it gets created:
548
+prom_histogram_observe("hist01", "-12.5");
549
+...
550
+
551
+# Definition of hist02 histogram with two labels method and IP and buckets [2.3,
552
+ 5.8, +Inf]:
553
+modparam("xhttp_prom", "prom_histogram", "name=hist02; label=method:IP; buckets=
554
+2.3:5.8");
555
+...
556
+# Observe 2.8 value in hist02 histogram with labels method and IP.
557
+# It creates the histogram if it does not exist.
558
+prom_histogram_observe("hist02", "2.8", "push", "192.168.0.1");
559
+# When listed the metric it will show lines like this:
560
+hist02_bucket{method="push", IP="192.168.0.1", le="2.300000"} 0 1592574659768
561
+hist02_bucket{method="push", IP="192.168.0.1", le="5.800000"} 1 1592574659768
562
+hist02_bucket{method="push", IP="192.168.0.1", le="+Inf"} 1 1592574659768
563
+hist02_sum{method="push", IP="192.168.0.1"} 2.800000 1592574659768
564
+hist02_count{method="push", IP="192.168.0.1"} 1 1592574659768
565
+
566
+...
567
+
568
+4.6.  prom_dispatch()
430 569
 
431 570
    Handle the HTTP request and generate a response.
432 571
 
433 572
    Available via KEMI framework as xhttp_prom.dispatch
434 573
 
435
-   Example 1.12. prom_dispatch usage
574
+   Example 1.16. prom_dispatch usage
436 575
 ...
437 576
 # Needed to use SIP frames as HTTP ones.
438 577
 tcp_accept_no_cl=yes
... ...
@@ -455,7 +594,7 @@ event_route[xhttp:request] {
455 594
 }
456 595
 ...
457 596
 
458
-   Example 1.13. prom_dispatch usage (more complete)
597
+   Example 1.17. prom_dispatch usage (more complete)
459 598
 
460 599
    Another example with counters and gauge:
461 600
 ...
... ...
@@ -526,7 +665,7 @@ kamailio_sl_sent_replies 15 1554839325427
526 665
 kamailio_sl_xxx_replies 0 1554839325461
527 666
 ...
528 667
 
529
-4.6.  prom_check_uri()
668
+4.7.  prom_check_uri()
530 669
 
531 670
    Check if path of HTTP URL equals /metrics. This avoids us to check hu
532 671
    variable from xHTTP module.
... ...
@@ -535,7 +674,7 @@ kamailio_sl_xxx_replies 0 1554839325461
535 674
 
536 675
    Available via KEMI framework as xhttp_prom.check_uri
537 676
 
538
-   Example 1.14. prom_check_uri usage
677
+   Example 1.18. prom_check_uri usage
539 678
 ...
540 679
 # Needed to use SIP frames as HTTP ones.
541 680
 tcp_accept_no_cl=yes
... ...
@@ -563,7 +702,8 @@ event_route[xhttp:request] {
563 702
    5.2. xhttp_prom.counter_inc
564 703
    5.3. xhttp_prom.gauge_reset
565 704
    5.4. xhttp_prom.gauge_set
566
-   5.5. xhttp_prom.metric_list_print
705
+   5.5. xhttp_prom.histogram_observe
706
+   5.6. xhttp_prom.metric_list_print
567 707
 
568 708
 5.1. xhttp_prom.counter_reset
569 709
 
... ...
@@ -577,7 +717,7 @@ event_route[xhttp:request] {
577 717
      * l1: value of second label (optional)
578 718
      * l2: value of the third label (optional)
579 719
 
580
-   Example 1.15. xhttp_prom.counter_reset usage
720
+   Example 1.19. xhttp_prom.counter_reset usage
581 721
                   ...
582 722
                   kamcmd xhttp_prom.counter_reset "cnt01" "push" "192.168.0.1"
583 723
                   ...
... ...
@@ -596,7 +736,7 @@ event_route[xhttp:request] {
596 736
      * l1: value of second label (optional)
597 737
      * l2: value of the third label (optional)
598 738
 
599
-   Example 1.16. xhttp_prom.counter_inc usage
739
+   Example 1.20. xhttp_prom.counter_inc usage
600 740
                   ...
601 741
                   kamcmd xhttp_prom.counter_inc "cnt01" 15 "push" "192.168.0.1"
602 742
                   ...
... ...
@@ -613,7 +753,7 @@ event_route[xhttp:request] {
613 753
      * l1: value of second label (optional)
614 754
      * l2: value of the third label (optional)
615 755
 
616
-   Example 1.17. xhttp_prom.gauge_reset usage
756
+   Example 1.21. xhttp_prom.gauge_reset usage
617 757
                   ...
618 758
                   kamcmd xhttp_prom.gauge_reset "gg01" "push" "192.168.0.1"
619 759
                   ...
... ...
@@ -631,12 +771,31 @@ event_route[xhttp:request] {
631 771
      * l1: value of second label (optional)
632 772
      * l2: value of the third label (optional)
633 773
 
634
-   Example 1.18. xhttp_prom.gauge_set usage
774
+   Example 1.22. xhttp_prom.gauge_set usage
635 775
                   ...
636 776
                   kamcmd xhttp_prom.gauge_set "gg01" -- -5.2
637 777
                   ...
638 778
 
639
-5.5. xhttp_prom.metric_list_print
779
+5.5. xhttp_prom.histogram_observe
780
+
781
+   Observe a number in a histogram. Select the histogram by its name and
782
+   labels.
783
+
784
+   Name: xhttp_prom.histogram_observe
785
+
786
+   Parameters:
787
+     * name: name of the histogram (mandatory)
788
+     * number: float value to observe in the histogram (mandatory)
789
+     * l0: value of the first label (optional)
790
+     * l1: value of second label (optional)
791
+     * l2: value of the third label (optional)
792
+
793
+   Example 1.23. xhttp_prom.histogram_observe usage
794
+                  ...
795
+                  kamcmd xhttp_prom.histogram_observe "hist01" -- -5.2
796
+                  ...
797
+
798
+5.6. xhttp_prom.metric_list_print
640 799
 
641 800
    List of all user defined metrics.
642 801
 
... ...
@@ -644,7 +803,10 @@ event_route[xhttp:request] {
644 803
 
645 804
    Parameters:none
646 805
 
647
-   Example 1.19. xhttp_prom.metric_list_print usage
806
+   NOTE:: If you list a lot of metrics you may need to increase buffer
807
+   size of your RPC transport layer.
808
+
809
+   Example 1.24. xhttp_prom.metric_list_print usage
648 810
                   ...
649 811
                   kamcmd xhttp_prom.metric_list_print
650 812
                   ...