Monitoring

The tool_monitoring Plugin makes it easy to integrate standard monitoring setups (such as Prometheus & Grafana) with any running Moodle instance.

Features

• 🍱 Just works: Ready-made with sensible Moodle metrics and a Prometheus endpoint out of the box.
• 🏗️ Extensible: To define your own metric, simply extend the metric class and register it for collection.
• 🗃️ Generic: Agnostic towards the monitoring software used; supports custom exporters.
• 🧑‍💻 Admin-friendly: Convenient admin dashboard to view and configure individual metrics and exporters.
• 🔧 Customizable: For advanced use, metrics can be configured and even tagged via the Moodle Tag API.

Admin Settings Dashboard

The admin dashboard can be found at /admin/tool/monitoring or by navigating to Site administration > Plugins > Admin tools > Monitoring > Overview.

See the documentation for the pre-installed metrics and the labels they are partitioned by.

The actual Prometheus endpoint is immediately accessible and can be reached at the route /monitoringexporter_prometheus/metrics.

Warning: The endpoint is unauthenticated by default. Until a prometheus_token is set, anyone who can reach the URL can see all enabled metrics with no credentials. Even though by default all new metrics are disabled, a token should be set before exposing the endpoint to any untrusted network.

Grouping metrics with tags (optional)

tool_monitoring allows you to easily group metrics by leveraging Moodle's Tag API. You can assign arbitrary tags (scoped to their own distinct "metrics" tag area) to any metric. Exporters can then provide a parameter to filter the produced metrics by the tags they carry. For example, the included Prometheus exporter accepts a tag query parameter in the URL. Passing a single tag name will filter out all metrics that do not carry that tag. Passing a comma-separated list of tags will ensure only metrics that carry all of those tags will be exported. (Note the AND-condition being applied here.) For implementation details, take a look at the Prometheus exporter class.

To assign tags to a metric, go to its configuration page. Then simply enter the tag names in the "Tags" field.

Clicking on a tag will filter the list of metrics accordingly.

Prometheus configuration

scrape_configs:
  # Choose whatever unique job name you like.
  - job_name: moodle
    # The default scheme is HTTP.
    scheme: https
    # If you have set an access token, provide it here.
    authorization:
      credentials: 'super-secure-secret'
    # Specify the full endpoint path. The default is just '/metrics'.
    # If Moodle routing is not fully configured, you have to prepend '/r.php' to the path.
    metrics_path: /monitoringexporter_prometheus/metrics
    # Specify the target host.
    static_configs:
      - targets: ['example.com']

Setting up a Grafana dashboard

This assumes you have configured Prometheus as described above. You can import the example Grafana dashboard from docs/examples/grafana_dashboard.json into grafana:

Go to "Dashboards" > "New" and select "import" and select the json-file or paste its content there. Select the Prometheus data source and click "import".

Documentation

Installation instructions, guides for adding your own metrics and exporter sub-plugins, and the full reference are in the README.

Copyright

© 2025 Daniel Fainberg, Martin Gauk, Sebastian Rupp, Malte Schmitz, Melanie Treitinger

Code, tests, and documentation written by and for humans. 🚫🤖