Prosody (0.10+) has a built-in mechanism for gathering and reporting internal metrics. Examples include reporting the number of connected users, number of stanzas processed.

⚠️ A note on configuration: statistics is a server-wide feature, all configuration options described on this page must be placed in the global section of the config file. Also to prevent inconsistent data reporting, these options cannot be changed at runtime.

Statistics providers

Although there is a common interface for modules to report their metrics to Prosody, you can choose how you want Prosody to handle these metrics. By default any gathering of metrics is disabled (to avoid any impact on performance when not in use). However you can easily enable one of Prosody's built-in statistics providers, or use an external one, by setting the 'statistics' option in your config file.

Built-in providers

The following providers are available in Prosody out of the box.


    statistics = "internal"

The internal provider supports collection and aggregation of metrics entirely within Prosody using no external dependencies. It stores the aggregated metrics in memory so they can be used by other modules, and examined in the telnet console for example.

If you want to integrate Prosody with a pull-based external monitoring system (such as Munin) you will want to use this provider so they can pull the stored metrics.


    statistics = "statsd"

The statsd provider pushes all metrics to an external statsd server (or anything that is compatible with the standard statsd protocol). It does not do any processing, aggregation or storage of metrics, which makes it suitable for high-volume servers.

You can configure the address and port of the statsd server like this:

    statistics_config = {
        statsd_server = "localhost";
        statsd_port = 8125;

The above settings are the defaults.

External providers

It is possible to use (and develop) external providers, to allow Prosody to push metrics to other services for monitoring and aggregation of metrics.

For example, to load an external provider called 'super_stats':

    statistics = ':super_stats'

The library will be loaded using Lua's require() function, so should be available in standard locations. It must implement the API described in util.statistics.

Collection interval

Some modules only report metrics when they are asked to, at intervals. You can control how often this collection happens using the 'statistics_interval' option. It defaults to 60 seconds.

To enable collection, add the statistics_interval option in the global section of the config:

statistics_interval = 60 -- the collection interval, in seconds

With this, statistics will be collected and processed once per minute. You may want to pick a different interval depending on your use case.


To add metrics to your module, use the module:measure() method, and follow the examples provided for different kinds of metrics.