argus-dpy 0.3.1

Operational Prometheus/OpenTelemetry metrics for discord.py bots, in one line.

argus-dpy

Operational Prometheus / OpenTelemetry metrics for discord.py bots, in one line.

from discord.ext import commands
from argus import Argus

bot = commands.AutoShardedBot(command_prefix="!", intents=...)
Argus(bot)          # the whole integration

Argus(bot) instruments shard latency, interaction/command throughput and outcomes, precise command duration, gateway throughput, rate-limit pressure and cache sizes, then serves a Prometheus /metrics endpoint and a live web dashboard on the bot's own event loop. It can also push to OpenTelemetry and drain per-guild events to ClickHouse. It never puts a guild, user, or channel id on a Prometheus label.

Install

pip install argus-dpy

Python 3.10+, discord.py >= 2.4. Optional extras: argus-dpy[otlp], argus-dpy[clickhouse]. A reference container is published at ghcr.io/astoristhebrave/argus.

Behaviour

Argus(bot) registers listeners synchronously, then starts an aiohttp server on the bot's loop once it is running. By default it serves the dashboard at / and metrics at /metrics on port 9191. Disable the dashboard with Argus(bot, dashboard=False); everything else is opt-in. Instrumentation is fail-open: it is counted and swallowed, never raised into your bot. See Architecture & invariants.

Minimal setup

The minimum is one line; everything else is opt-in via kwargs or ARGUS_* environment variables (kwargs override env override defaults).

Argus(bot)   # metrics at /metrics, dashboard at /, on port 9191

To protect the dashboard, set one env var on the host that runs the bot — Argus picks it up automatically. The dashboard is served by Argus in the same process, so there is nothing separate to host or wire up:

ARGUS_DASHBOARD_AUTH_TOKEN=your-secret   # gates / and /api/*; /metrics stays scrapeable

Open the dashboard once with the token and it is remembered in the browser: http://your-host:9191/?token=your-secret.

Common options

kwarg / env	default	meaning
port / ARGUS_PORT	9191	server port
dashboard_auth_token / ARGUS_DASHBOARD_AUTH_TOKEN	—	gate the dashboard + APIs
grafana_url / ARGUS_GRAFANA_URL	—	link/embed your Grafana boards
cluster_id / ARGUS_CLUSTER_ID	default	label for clustered deploys
enable_per_guild / ARGUS_ENABLE_PER_GUILD	false	per-guild analytics path
otlp_endpoint / ARGUS_OTLP_ENDPOINT	—	also push metrics via OTLP

Every option, precedence and parsing rule is in Configuration. New here? Start with the FAQ.

Metrics

Aggregate, bounded-cardinality metrics: per-shard latency and up state, per-cluster guild/user/voice/emoji/sticker/channel counts, uptime, registered commands, interaction and command rates with success/error split, precise command-duration histogram, gateway throughput, shard dis/reconnects, log and rate-limit counters. Every counter and the histogram carry a cluster label.

Full list with labels: Metrics Reference.

Dashboard

A React SPA bundled into the wheel, served at /: overview, interactions, gateway, your Grafana boards, and per-guild analytics. Reads metrics live over SSE with a polling fallback. Set dashboard_auth_token for anything public. See Dashboard.

Per-guild analytics

Per-guild, per-user questions never go to Prometheus (cardinality). With enable_per_guild + clickhouse_dsn, Argus drains per-guild events to ClickHouse (batched, non-blocking) and the dashboard's Analytics section serves per-guild command counts and average durations. See History & ClickHouse.

Grafana, OTLP, clustering

docker compose up -d brings up a provisioned Prometheus + Grafana with three dashboards. Set otlp_endpoint to also push via OpenTelemetry. Run one Argus per process with a distinct cluster_id for clustered bots. See Clustering and OTLP.

Why no per-guild Prometheus labels?

guild_id/user_id/channel_id are unbounded; as labels they explode Prometheus at scale and are useless to visualise. Argus forbids them by construction and routes per-entity questions to the analytical path instead.

Contributing & license

Contributions are accepted under the DCO; see CONTRIBUTING.md. Licensed under AGPL-3.0-or-later (network use counts as distribution) — see LICENSE.

---

See the full wiki for the in-depth guides and explanations.