Mercurial > prosody-modules

annotate mod_prometheus/README.markdown @ 4688:05725276fac0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_bookmarks2: Use same default as mod_pep for max_items Should fix the issue with max items until the proper "max" can be used, by following the configured max. While "max" is already in trunk, it's not easily usable in 0.11.x This limit and option was added to mod_pep in Prosody rev aefb96a52f5f
author Kim Alvefur <zash@zash.se>
date Wed, 15 Sep 2021 17:39:37 +0200
parents f4ab80f72d63
children 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 ------- -------------