prosody-modules
886c985ece61
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 @ 6195:886c985ece61

mod_lastlog2: Skip initializing internal API (and storage) in prosodyctl Initializing storage in the global context under prosodyctl causes the module.command to fail to execute because the storage module has already been loaded. Introduced in 7b722955c59b
author Kim Alvefur <zash@zash.se>
date Sat, 08 Feb 2025 14:12:18 +0100
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 ------- -------------