prosody-modules
8ecd53452af8
mod_prometheus/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_prometheus/README.md @ 6217:8ecd53452af8

mod_push2: LMC stanzas are not important
author Stephen Paul Weber <singpolyma@singpolyma.net>
date Tue, 25 Mar 2025 15:20:35 -0500
parent 6047:8c3bacf3549e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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:
6047
8c3bacf3549e mod_prometheus: add label, update compability
Menel <menel@snikket.de>
parents: 6003
diff changeset
3 - Stage-Obsolete
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
4 - Statistics
3125
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
5 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
6 ...
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
7
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
8 Description
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
9 ===========
3125
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
10
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
11 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
12 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
13
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
14 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
15 more information.
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
16
07a2ba55de4d mod_prometheus: Add a new statistics export module, for Prometheus.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
diff changeset
17 [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
18
5413
c90011054335 mod_prometheus: Wrap pointer to mod_http_openmetrics in a box
Kim Alvefur <zash@zash.se>
parents: 4790
diff changeset
19 ::: {.alert .alert-info}
6047
8c3bacf3549e mod_prometheus: add label, update compability
Menel <menel@snikket.de>
parents: 6003
diff changeset
20 **Note:** For use with Prosody 0.12 or later we recommend the bundled
4790
bb66e87a3604 mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents: 4545
diff changeset
21 [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
22 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
23 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
24 :::
4790
bb66e87a3604 mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents: 4545
diff changeset
25
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
26 Configuration
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
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
29 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
30 requires Prosody’s [internal statistics
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
31 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
32 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
33 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
34
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
35 ```lua
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
36 statistics = "internal"
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
37 statistics_interval = 15 -- in seconds
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
38 ```
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
39
4239
313e293f44b3 mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3399
diff changeset
40 ::: {.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
41 **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
42 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
43 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
44 :::
313e293f44b3 mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3399
diff changeset
45
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
46 See also the documentation of Prosody’s [HTTP
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
47 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
48 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
49 http://localhost:5280/metrics
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
50
4545
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
51 Scrape interval vs statistics_interval
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
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
54 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
55 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
56 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
57
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
58 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
59 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
60 and similar.
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
61
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
62 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
63 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
64
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
65 Compatibility
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
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
68 ------- -------------
6047
8c3bacf3549e mod_prometheus: add label, update compability
Menel <menel@snikket.de>
parents: 6003
diff changeset
69 0.12 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
70 0.11 Works
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
71 0.10 Works
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
72 0.9 Does not work
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
73 ------- -------------