Prometheus Metrics Integration
Monitor IRC network statistics with Prometheus and Grafana
Overview
IRC Driven provides OpenMetrics-compatible endpoints that can be scraped by Prometheus for monitoring IRC network statistics in real-time. This allows you to:
- Track network health and growth over time
- Set up alerts for unusual activity
- Create beautiful Grafana dashboards
- Monitor multiple networks from a single Prometheus instance
- Analyze historical trends
Available Endpoints
Network-Specific Metrics
URL: /network/<network_name>/metrics/
Access: Public (no authentication required)
Metrics Provided
irc_network_users- Total users on the networkirc_network_channels- Total number of channelsirc_network_servers- Total number of serversirc_network_last_update- Timestamp of last updateirc_channel_users- User count per channel (with labels)irc_server_users- User count per server (with labels)irc_network_info- Network metadata (region, etc.)
Query Parameters
| Parameter | Description | Default | Example |
|---|---|---|---|
limit |
Maximum number of channels to include | All channels | ?limit=500 |
min_users |
Minimum user count for channels | 0 (all channels) | ?min_users=10 |
Examples
# Get all channels
curl https://www.ircdriven.com/network/Libera.Chat/metrics/
# Get top 500 channels only
curl https://www.ircdriven.com/network/Libera.Chat/metrics/?limit=500
# Get channels with at least 5 users (reduces noise)
curl https://www.ircdriven.com/network/Libera.Chat/metrics/?min_users=5
# Combine both parameters
curl https://www.ircdriven.com/network/Libera.Chat/metrics/?limit=100&min_users=50Global Metrics (All Networks)
URL: /metrics/openmetrics/
Access: Pass the site's scrape secret as query parameter ?secret=YOUR_SECRET or header X-Prometheus-Secret: YOUR_SECRET. (Site operators set PROMETHEUS_SCRAPE_SECRET in their environment; use the same value when scraping.)
Metrics Provided
irc_networks_total- Number of active (non-disabled) networksirc_networks_disabled- Number of disabled networksirc_networks_total_all- Total networks (active + disabled)irc_network_users{network="...", disabled="0"|"1"}- Users per networkirc_network_channels,irc_network_servers- Per network (same labels)irc_network_last_update- Last stats update time (Unix ms); use for staleness / healthirc_network_disabled{network="..."}- 1 if disabled, 0 if activeirc_global_users,irc_global_channels,irc_global_servers- Totals across active networks
Use disabled="0" in queries for active networks only. For network health, e.g. minutes since last update: ((time()*1000) - irc_network_last_update{disabled="0"}) / 60000.
Prometheus Configuration
Scraping a Single Network
Add this to your prometheus.yml file:
scrape_configs:
- job_name: 'irc_libera'
metrics_path: '/network/Libera.Chat/metrics/'
params:
min_users: ['5'] # Optional: filter out empty channels
static_configs:
- targets: ['www.ircdriven.com']
scheme: https
scrape_interval: 5m # Adjust based on your needsScraping Multiple Networks
scrape_configs:
- job_name: 'irc_networks'
static_configs:
- targets:
- 'Libera.Chat'
- 'OFTC'
- 'IRCnet'
metrics_path: '/network/__param_target__/metrics/'
params:
min_users: ['3']
relabel_configs:
- source_labels: [__address__]
target_label: __param_target
- source_labels: [__param_target]
target_label: network
- target_label: __address__
replacement: www.ircdriven.com:443
scheme: https
scrape_interval: 5mScraping Global Metrics
Use the shared secret (query param or header). Replace YOUR_PROMETHEUS_SCRAPE_SECRET with the value configured on the site.
scrape_configs:
- job_name: 'ircdriven-website-irc-global'
metrics_path: '/metrics/openmetrics/'
scheme: https
params:
secret: ['YOUR_PROMETHEUS_SCRAPE_SECRET']
static_configs:
- targets: ['www.ircdriven.com:443']
scrape_interval: 60s
tls_config:
insecure_skip_verify: falseGrafana Dashboard Examples
Network Overview Panel
Display current user count with trend:
irc_network_users{network="Libera.Chat"}Top 10 Channels by User Count
topk(10, irc_channel_users{network="Libera.Chat"})Total Users Across All Networks
sum(irc_network_users)Network Growth Rate (24h)
irc_network_users{network="Libera.Chat"}
- irc_network_users{network="Libera.Chat"} offset 24hAlert: Network Down or Major Drop
- alert: NetworkUsersDrop
expr: |
(irc_network_users - irc_network_users offset 5m) / irc_network_users < -0.5
for: 5m
labels:
severity: critical
annotations:
summary: "IRC network user count dropped significantly"Best Practices
Filter Empty Channels
Use min_users parameter to reduce metric cardinality and focus on active channels.
Appropriate Intervals
Set scrape intervals to 5-15 minutes. IRC stats don't change rapidly enough to warrant more frequent scraping.
Use Labels
Leverage network, channel, and server labels in your queries for detailed analysis.
Troubleshooting
- Verify the endpoint URL is correct and accessible
- Check Prometheus logs for scrape errors
- Ensure SSL/TLS certificates are valid if using HTTPS
- Verify network name spelling (case-sensitive)
- Use
min_usersparameter to filter out empty/small channels - Set a reasonable
limitparameter (e.g., 500-1000) - Focus on per-network aggregates instead of per-channel metrics
- Increase Prometheus retention settings if needed
- Use
/metrics/openmetrics/with thesecretquery parameter orX-Prometheus-Secretheader - The value must match exactly (no extra spaces; check for a leading/trailing character)
- Obtain the scrape secret from the site operator; it is set as
PROMETHEUS_SCRAPE_SECRETon the server