Software /
code /
prosody-modules
Annotate
mod_prometheus/README.markdown @ 5656:d832a5e10c04
mod_bidi: Add warning about use with 0.12
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Sun, 27 Aug 2023 15:28:53 +0200 |
parent | 5413:c90011054335 |
rev | line source |
---|---|
3125
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
1 --- |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
2 labels: |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
3 - Statistics |
3125
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
4 summary: Implementation of the Prometheus protocol |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
5 ... |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
6 |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
7 Description |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
8 =========== |
3125
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
9 |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
10 This module implements the Prometheus reporting protocol, allowing you |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
11 to collect statistics directly from Prosody into Prometheus. |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
12 |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
13 See the [Prometheus documentation][prometheusconf] on the format for |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
14 more information. |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
15 |
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
16 [prometheusconf]: https://prometheus.io/docs/instrumenting/exposition_formats/ |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
17 |
5413
c90011054335
mod_prometheus: Wrap pointer to mod_http_openmetrics in a box
Kim Alvefur <zash@zash.se>
parents:
4790
diff
changeset
|
18 ::: {.alert .alert-info} |
4790
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4545
diff
changeset
|
19 **Note:** For use with Prosody trunk (0.12) we recommend the bundled |
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4545
diff
changeset
|
20 [mod_http_openmetrics](https://prosody.im/doc/modules/mod_http_openmetrics) |
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4545
diff
changeset
|
21 instead. This module (mod_prometheus) will continue to be available in the |
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4545
diff
changeset
|
22 community repository for use with older Prosody versions. |
5413
c90011054335
mod_prometheus: Wrap pointer to mod_http_openmetrics in a box
Kim Alvefur <zash@zash.se>
parents:
4790
diff
changeset
|
23 ::: |
4790
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4545
diff
changeset
|
24 |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
25 Configuration |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
26 ============= |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
27 |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
28 mod\_prometheus itself doesn’t have any configuration option, but it |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
29 requires Prosody’s [internal statistics |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
30 provider](https://prosody.im/doc/statistics#built-in_providers) to be |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
31 enabled. You may also want to change the default collection interval |
4545
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
32 to the one your statistics consumer is using. See below for more information. |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
33 |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
34 ```lua |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
35 statistics = "internal" |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
36 statistics_interval = 15 -- in seconds |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
37 ``` |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
38 |
4239
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3399
diff
changeset
|
39 ::: {.alert .alert-warning} |
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3399
diff
changeset
|
40 **NOTE:** Make sure to put the statistics variables in the global section of |
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3399
diff
changeset
|
41 the configuration, **not** in a `VirtualHost` or `Component` section. You can |
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3399
diff
changeset
|
42 use `prosodyctl check` if you are unsure and want to check your configuration. |
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3399
diff
changeset
|
43 ::: |
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3399
diff
changeset
|
44 |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
45 See also the documentation of Prosody’s [HTTP |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
46 server](https://prosody.im/doc/http), since Prometheus is an HTTP |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
47 protocol that is how you can customise its URL. The default one being |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
48 http://localhost:5280/metrics |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
49 |
4545
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
50 Scrape interval vs statistics_interval |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
51 -------------------------------------- |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
52 |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
53 The `statistics_interval` should be set to `"manual"` on trunk if and only |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
54 if you have a single Prometheus instance scraping Prosody. This will allow |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
55 the internal statistics gathering to run optimally. |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
56 |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
57 If you have multiple instances scraping Prosody, set `statistics_interval` |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
58 to the scrape interval of Prometheus to avoid errors in rate calculations |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
59 and similar. |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
60 |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
61 Future work will allow the use of `"manual"` with multiple Prometheus |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
62 instances and varying scrape intervals (stay tuned). |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4239
diff
changeset
|
63 |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
64 Compatibility |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
65 ============= |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
66 |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
67 ------- ------------- |
4790
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4545
diff
changeset
|
68 trunk Works (but replaced by [mod_http_openmetrics](https://prosody.im/doc/modules/mod_http_openmetrics)) |
3399
39ec478a752e
mod_prometheus/README: Add line for 0.11 in compat section
Kim Alvefur <zash@zash.se>
parents:
3315
diff
changeset
|
69 0.11 Works |
3315
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
70 0.10 Works |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
71 0.9 Does not work |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3125
diff
changeset
|
72 ------- ------------- |