Monitoring with Prometheus and Grafana

Monitoring with Prometheus and Grafana

This page documents the recommended Prometheus/Grafana workflow for Mediabot v3.

Mediabot can expose Prometheus metrics when the [metrics] section is enabled in the instance configuration file. The repository also ships an importable Grafana dashboard under:

contrib/grafana/

The recommended dashboard is the hourly community dashboard.

It is designed for real IRC usage, including low-activity channels, multi-channel bots, and multi-instance deployments.

---

Why hourly dashboards?

IRC activity is often bursty.

A channel may be perfectly healthy even if it does not generate enough traffic to make a per-minute graph interesting. Short-window graphs can look empty, noisy, or misleading on quiet communities.

The hourly dashboard intentionally uses hourly views such as:

Lines / hour
Commands / hour

This makes it easier to see trends over realistic time ranges:

• which channels are active today;
• which bot commands are actually used;
• whether activity is increasing or fading;
• whether an instance is alive and exporting metrics;
• how activity is distributed across bot/channel pairs.

---

Enable metrics in Mediabot

Metrics are enabled per instance.

In the instance configuration file, enable the [metrics] section:

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

When running multiple Mediabot instances on the same host, every metrics-enabled instance must use a unique port:

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

Instances with metrics disabled will not appear in Prometheus or Grafana. That is expected.

---

Validate the metrics endpoint

From the host running the bot:

curl -s http://127.0.0.1:9108/metrics | head

A useful quick check:

curl -s http://127.0.0.1:9108/metrics | grep '^mediabot_'

Expected metric families include, depending on enabled features and runtime state:

mediabot_up
mediabot_irc_connected
mediabot_db_connected
mediabot_uptime_seconds
mediabot_channels_managed
mediabot_channel_lines_in_total
mediabot_channel_commands_total
mediabot_channel_commands_by_name_total
mediabot_commands_public_total
mediabot_commands_private_total
mediabot_commands_partyline_total
mediabot_commands_by_name_total
mediabot_auth_success_total
mediabot_auth_failure_total
mediabot_partyline_logins_total
mediabot_partyline_sessions_current
mediabot_build_info

---

URL and IRC life metrics

Mediabot 3.3 exposes counters that make IRC activity and URL title handling easier to graph:

mediabot_urltitle_requests_total{type="youtube|instagram|spotify|applemusic|facebook|x_twitter|generic"}
mediabot_nick_changes_total
mediabot_joins_total{channel="#channel"}
mediabot_parts_total{channel="#channel"}

Useful Grafana panels:

• URL title requests by type;
• nick changes over time, useful for netsplit-like bursts;
• joins and parts by channel;
• channel activity correlated with command usage.

Social/community metrics

Mediabot 3.3 exposes counters for the social/community layer.

Depending on enabled features and runtime activity, useful metric families include:

mediabot_wordcount_requests_total
mediabot_karmahist_requests_total
mediabot_achievements_unlocked_total{achievement="..."}
mediabot_duel_total{channel="#channel"}
mediabot_horoscope_total
mediabot_compat_total{channel="#channel"}
mediabot_quotegame_correct_total
mediabot_mood_total{channel="#channel"}
mediabot_chronos_total{channel="#channel"}
mediabot_observatory_total{channel="#channel"}

Suggested panels:

• social commands over time;
• achievement unlocks by achievement name;
• duel and quotegame activity by channel;
• mood/observatory usage by channel;
• wordcount and karmahist request volume;
• correlation between mediabot_channel_lines_in_total and social command usage.

For quiet channels, prefer hourly or daily rates over per-minute panels.

Prometheus scrape example

A minimal Prometheus scrape job can look like this:

scrape_configs:
  - job_name: mediabot
    static_configs:
      - targets:
          - 127.0.0.1:9108
        labels:
          instance_name: dev

      - targets:
          - 127.0.0.1:9109
        labels:
          instance_name: production

For remote instances, replace 127.0.0.1 with the reachable scrape target.

Use a stable instance_name label for each bot instance. The Grafana dashboard uses this label for filtering and grouping.

---

Import the Grafana dashboard

The dashboard JSON is located under:

contrib/grafana/

Recommended file:

grafana_mediabot_community_hourly_v3.json

Import flow:

1. Open Grafana.
2. Go to Dashboards.
3. Choose New / Import.
4. Upload or paste the JSON dashboard.
5. Select your Prometheus datasource when Grafana asks.
6. Open the dashboard.
7. Use the Bot and Channel selectors.

The dashboard includes a hidden Prometheus datasource variable so the panels do not need to be edited one by one after import.

Grafana still needs an existing Prometheus datasource. The dashboard does not create the datasource automatically.

---

Multi-instance behavior

The dashboard supports both simple and multi-instance deployments.

Single instance:

one bot -> one metrics endpoint -> one instance_name

Multi-instance:

bot A -> metrics port A -> instance_name A
bot B -> metrics port B -> instance_name B
bot C -> metrics port C -> instance_name C

If an instance does not expose metrics, it will not appear in the dashboard.

Channel graphs are grouped by bot/channel where needed, so selecting all instances does not hide which bot produced the activity.

---

Recommended dashboard time range

The hourly dashboard is intended for longer ranges than old per-minute dashboards.

Good defaults:

last 24 hours
last 7 days
last 30 days

For very quiet bots, use last 7 days or last 30 days.

---

Troubleshooting

The dashboard imports but shows no data

Check the metrics endpoint:

curl -s http://127.0.0.1:9108/metrics | grep '^mediabot_'

Then check Prometheus targets.

Common causes:

• metrics are disabled in the Mediabot config;
• Prometheus is not scraping the endpoint;
• the wrong port is configured;
• the instance is not running;
• Grafana is using the wrong Prometheus datasource;
• the selected instance_name or channel filter has no matching data.

Only one instance appears

Check that every metrics-enabled bot has:

• a unique METRICS_PORT;
• a Prometheus scrape target;
• a distinct instance_name label.

Graphs look flat

Use a longer time range.

Hourly graphs are designed for real IRC activity. A quiet bot may need a 7-day or 30-day view to show meaningful trends.

---

Related pages

• Configuration
• Running with systemd
• Troubleshooting

---

Social and observability metrics

Mediabot 3.3 exposes metrics for social/community commands.

Examples include:

mediabot_observatory_total
mediabot_leaderboard_total
mediabot_chronos_total
mediabot_quotegame_started_total
mediabot_quotegame_correct_total
mediabot_mood_total
mediabot_compat_total
mediabot_duel_total
mediabot_wordcount_requests_total
mediabot_karmahist_requests_total

The exact label set depends on the implementation and command.

Useful dashboard ideas:

• command usage by channel;
• observatory calls by channel;
• quote game starts/correct answers;
• duel usage;
• leaderboard/chronos usage;
• achievements unlocked.