Monitoring Mediabot with Prometheus and Grafana

Mediabot can now expose Prometheus metrics and be monitored cleanly in Grafana.

The goal is simple:

• know whether the bot is running
• know whether it is still connected to IRC
• see channel activity
• see which commands are used the most
• track Partyline activity and a few administration actions

This post provides a simple and reusable base for the community, with:

• a minimal Mediabot configuration
• a minimal Prometheus configuration
• a generic Grafana dashboard
• a setup that works very well with a single bot
• and a path to extend it later to multiple bots

1. Mediabot requirements

In mediabot.conf, add:

[metrics]
METRICS_ENABLED=1
METRICS_BIND=127.0.0.1
METRICS_PORT=9108

Important note

• 127.0.0.1 is perfect if Prometheus runs on the same machine as Mediabot
• if Prometheus scrapes the bot from another machine, you will need a reachable bind address such as 0.0.0.0, and proper firewall filtering

Once the bot has been restarted, you should be able to verify this:

curl http://127.0.0.1:9108/metrics

2. Metrics used

The dashboard relies on metrics such as:

• mediabot_up
• mediabot_build_info
• mediabot_irc_connected
• mediabot_db_connected
• mediabot_channels_managed
• mediabot_uptime_seconds
• mediabot_commands_public_total
• mediabot_commands_private_total
• mediabot_commands_partyline_total
• mediabot_channel_lines_in_total
• mediabot_channel_commands_total
• mediabot_channel_commands_by_name_total
• mediabot_rehash_total
• mediabot_restart_total
• mediabot_jump_total
• mediabot_auth_success_total
• mediabot_auth_failure_total
• mediabot_partyline_sessions_current
• mediabot_partyline_logins_total

3. Minimal Prometheus configuration

Here is a simple example for a single bot:

scrape_configs:
  - job_name: "mediabot"
    scrape_interval: 15s
    metrics_path: /metrics
    static_configs:
      - targets:
          - "127.0.0.1:9108"
        labels:
          service: "mediabot"
          instance_name: "mediabot"

After editing the configuration, verify it and reload Prometheus:

promtool check config /path/to/prometheus.yml
curl -X POST http://127.0.0.1:9090/-/reload

Quick check in Prometheus:

mediabot_up

If everything is fine, the query should return 1.

4. Importing the dashboard into Grafana

1. Go to Dashboards
2. Click New
3. Click Import
4. Upload the dashboard JSON file
5. Choose the Prometheus datasource
6. Confirm

The generic dashboard provided here is designed to be:

• readable with a single bot
• reusable
• rich enough to be useful immediately

5. What the dashboard shows

Bot health

• Bot Up
• IRC Connected
• DB Connected
• Managed Channels
• Uptime
• Lines / min

Activity

• Public / Private / Partyline Commands / min
• Lines / min by Channel

Usage

• Commands / min by Channel
• Top Commands by Channel
• Top Public Commands Global

Administration

• Rehash / Restart / Jump
• Auth / Partyline

Metadata

• Build Info

6. Why a generic dashboard instead of a multi-bot dashboard

For the community, the most useful entry point is a dashboard that works immediately with:

• a single Mediabot instance
• a short Prometheus configuration
• no dependency on a custom or unusual infrastructure

A multi-instance variant is obviously possible later, but it should not be the default entry point.

7. Going further

When several bots are deployed, you only need to add more targets in Prometheus, each with its own instance_name.

Example:

scrape_configs:
  - job_name: "mediabot"
    scrape_interval: 15s
    metrics_path: /metrics
    static_configs:
      - targets: ["127.0.0.1:9108"]
        labels:
          service: "mediabot"
          instance_name: "bot-main"

      - targets: ["bot2.example.org:9108"]
        labels:
          service: "mediabot"
          instance_name: "bot2"

8. Conclusion

With a small set of well-chosen metrics, Prometheus and Grafana provide a much clearer view of:

• the real state of the bot
• IRC activity
• command usage
• Partyline activity
• and day-to-day operations

It is clean, standard, easy to extend, and far more comfortable than relying only on logs.

9. JSON file to import

• grafana_mediabot_community_single_bot_v2.json
• optionally later, a more advanced multi-instance / multi-channel variant