author | Matthew Wild <mwild1@gmail.com> |
Tue, 16 Apr 2024 12:58:08 +0100 | |
changeset 5889 | 54b451c3790c |
parent 5417 | c90011054335 |
permissions | -rw-r--r-- |
3129
07a2ba55de4d
mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff
changeset
|
1 |
--- |
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
2 |
labels: |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
3 |
- Statistics |
3129
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 |
|
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
7 |
Description |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
8 |
=========== |
3129
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/ |
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
17 |
|
5417
c90011054335
mod_prometheus: Wrap pointer to mod_http_openmetrics in a box
Kim Alvefur <zash@zash.se>
parents:
4794
diff
changeset
|
18 |
::: {.alert .alert-info} |
4794
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4549
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:
4549
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:
4549
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:
4549
diff
changeset
|
22 |
community repository for use with older Prosody versions. |
5417
c90011054335
mod_prometheus: Wrap pointer to mod_http_openmetrics in a box
Kim Alvefur <zash@zash.se>
parents:
4794
diff
changeset
|
23 |
::: |
4794
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4549
diff
changeset
|
24 |
|
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
25 |
Configuration |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
26 |
============= |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
27 |
|
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
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:
3129
diff
changeset
|
29 |
requires Prosody’s [internal statistics |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
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:
3129
diff
changeset
|
31 |
enabled. You may also want to change the default collection interval |
4549
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
diff
changeset
|
32 |
to the one your statistics consumer is using. See below for more information. |
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
33 |
|
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
34 |
```lua |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
35 |
statistics = "internal" |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
36 |
statistics_interval = 15 -- in seconds |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
37 |
``` |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
38 |
|
4243
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3403
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:
3403
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:
3403
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:
3403
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:
3403
diff
changeset
|
43 |
::: |
313e293f44b3
mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3403
diff
changeset
|
44 |
|
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
45 |
See also the documentation of Prosody’s [HTTP |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
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:
3129
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:
3129
diff
changeset
|
48 |
http://localhost:5280/metrics |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
49 |
|
4549
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
diff
changeset
|
50 |
Scrape interval vs statistics_interval |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
diff
changeset
|
51 |
-------------------------------------- |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
diff
changeset
|
52 |
|
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
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:
4243
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:
4243
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:
4243
diff
changeset
|
56 |
|
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
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:
4243
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:
4243
diff
changeset
|
59 |
and similar. |
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
diff
changeset
|
60 |
|
f4ab80f72d63
mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents:
4243
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:
4243
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:
4243
diff
changeset
|
63 |
|
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
64 |
Compatibility |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
65 |
============= |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
66 |
|
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
67 |
------- ------------- |
4794
bb66e87a3604
mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents:
4549
diff
changeset
|
68 |
trunk Works (but replaced by [mod_http_openmetrics](https://prosody.im/doc/modules/mod_http_openmetrics)) |
3403
39ec478a752e
mod_prometheus/README: Add line for 0.11 in compat section
Kim Alvefur <zash@zash.se>
parents:
3319
diff
changeset
|
69 |
0.11 Works |
3319
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
70 |
0.10 Works |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
71 |
0.9 Does not work |
bbf20293bc43
mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
3129
diff
changeset
|
72 |
------- ------------- |