Mercurial > prosody-modules

annotate mod_prometheus/README.markdown @ 5156:a8df4d2447d0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_unified_push: README: Update docs
author Matthew Wild <mwild1@gmail.com>
date Sat, 14 Jan 2023 17:59:40 +0000
parents bb66e87a3604
children c90011054335
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:
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
4790
bb66e87a3604 mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents: 4545
diff changeset
18 **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
19 [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
20 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
21 community repository for use with older Prosody versions.
bb66e87a3604 mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents: 4545
diff changeset
22
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
23 Configuration
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
24 =============
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
25
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
26 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
27 requires Prosody’s [internal statistics
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
28 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
29 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
30 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
31
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
32 ```lua
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
33 statistics = "internal"
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
34 statistics_interval = 15 -- in seconds
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
35 ```
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
36
4239
313e293f44b3 mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3399
diff changeset
37 ::: {.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
38 **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
39 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
40 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
41 :::
313e293f44b3 mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3399
diff changeset
42
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
43 See also the documentation of Prosody’s [HTTP
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
44 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
45 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
46 http://localhost:5280/metrics
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
47
4545
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
48 Scrape interval vs statistics_interval
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
49 --------------------------------------
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
50
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
51 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
52 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
53 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
54
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
55 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
56 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
57 and similar.
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
58
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
59 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
60 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
61
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
62 Compatibility
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
63 =============
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
64
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
65 ------- -------------
4790
bb66e87a3604 mod_prometheus: Update docs to reference mod_http_openmetrics for trunk/0.12
Matthew Wild <mwild1@gmail.com>
parents: 4545
diff changeset
66 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
67 0.11 Works
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
68 0.10 Works
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
69 0.9 Does not work
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
70 ------- -------------