prosody-modules
b9af1ccac98b
mod_prometheus/README.markdown

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.markdown @ 4758:b9af1ccac98b

mod_measure_malloc: Fix accidental global variable write [luacheck]
author Kim Alvefur <zash@zash.se>
date Sun, 07 Nov 2021 14:25:58 +0100
parent 4545:f4ab80f72d63
child 4790:bb66e87a3604
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
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
18 Configuration
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
19 =============
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
20
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
21 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
22 requires Prosody’s [internal statistics
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
23 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
24 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
25 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
26
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
27 ```lua
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
28 statistics = "internal"
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
29 statistics_interval = 15 -- in seconds
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
30 ```
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
31
4239
313e293f44b3 mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3399
diff changeset
32 ::: {.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
33 **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
34 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
35 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
36 :::
313e293f44b3 mod_prometheus: Warn users to put statistics settings in the global section
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3399
diff changeset
37
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
38 See also the documentation of Prosody’s [HTTP
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
39 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
40 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
41 http://localhost:5280/metrics
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
42
4545
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
43 Scrape interval vs statistics_interval
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
44 --------------------------------------
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
45
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
46 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
47 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
48 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
49
f4ab80f72d63 mod_prometheus: Update readme with "manual" statistics interval
Jonas Schäfer <jonas@wielicki.name>
parents: 4239
diff changeset
50 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
51 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
52 and similar.
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 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
55 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
56
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
57 Compatibility
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
58 =============
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
59
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
60 ------- -------------
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
61 trunk Works
3399
39ec478a752e mod_prometheus/README: Add line for 0.11 in compat section
Kim Alvefur <zash@zash.se>
parents: 3315
diff changeset
62 0.11 Works
3315
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
63 0.10 Works
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
64 0.9 Does not work
bbf20293bc43 mod_prometheus: Add more documentation.
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 3125
diff changeset
65 ------- -------------