mod_http_openmetrics Export OpenMetrics-compatible monitoring data

This module implements the OpenMetrics reporting protocol, pioneered by the Prometheus application monitoring tool. It allows you to monitor the health, status, activity and resource usage of a running Prosody instance.

See the Prometheus documentation on the format for more information.

Usage

Configuration

mod_http_openmetrics itself does not collect any metrics about Prosody, it only exposes what is already collected. To enable collection of metrics you need to activate Prosody’s internal statistics provider. You may also want to change the default collection interval to the one your statistics consumer is using. See below for more information.

modules_enabled = {
    -- other global modules etc ...
    "http_openmetrics"
}
statistics = "internal"
statistics_interval = "manual"

Note: Make sure to put the statistics variables in the global section of the configuration, not in a VirtualHost or Component section. You can use prosodyctl check if you are unsure and want to check your configuration.

The default URL to the module is http://localhost:5280/metrics. As with all modules using the built-in HTTP server, you can customise this using Prosody’s HTTP server configuration.

Scrape interval vs statistics_interval

The statistics_interval should be set to "manual" if, and only if, you have a single Prometheus instance scraping Prosody. This will allow the internal statistics gathering to run optimally.

If you have multiple Prometheus instances scraping Prosody, set statistics_interval to the scrape interval of Prometheus to avoid errors in rate calculations and similar.

Future work will allow the use of "manual" with multiple Prometheus instances and varying scrape intervals (stay tuned).

Access control

By default this module will deny any requests that don’t come from localhost (specifically 127.0.0.1 or ::1). Note that if you have set up a reverse proxy that forwards arbitrary paths to Prosody, this may expose your metrics publicly to the internet unless your proxy is adding the X-Forwarded-For header.

To configure custom IP addresses that should be allowed, set openmetrics_allow_ips:

openmetrics_allow_ips = { "127.0.0.1", "::1", "192.168.0.54" }

Or specify an IP range using openmetrics_allow_cidr:

openmetrics_allow_cidr = "192.168.0.0/24"

Compatibility

This module was added in Prosody 0.12.0. For earlier versions, refer to mod_prometheus in the community module repository.