FAQ

FAQ

Short answers to the things people hit first. See Configuration and Dashboard for the full detail.

Do I need to configure anything?

No. Argus(bot) is the whole integration: metrics at /metrics, the dashboard at /, on port 9191. Everything else is opt-in.

How do I protect the dashboard? Where does the token go?

Set one environment variable on the host/process that runs your bot:

ARGUS_DASHBOARD_AUTH_TOKEN=your-secret

Argus reads it automatically (no kwarg needed) and uses it for both serving and gating. There is nothing else to host: the dashboard is served by Argus inside your bot process, not as a separate app. The token gates / and every /api/* route; /metrics and /healthz stay open so a Prometheus scraper does not need it.

You can also pass it in code: Argus(bot, dashboard_auth_token="..."). The kwarg wins over the env var if both are set.

How do viewers log in?

Open the dashboard once with the token in the URL and it is remembered in that browser (localStorage):

http://your-host:9191/?token=your-secret

After that, plain http://your-host:9191/ works. Programmatic clients send Authorization: Bearer your-secret.

"I host the dashboard separately" — how?

You do not. Argus serves the SPA from the same aiohttp server as /metrics, on your bot's event loop. If you want it on a public URL, put a reverse proxy in front of the bot's port and set the token. If you want it on a different path or port, use dashboard_path / port.

How do I turn the dashboard off?

Argus(bot, dashboard=False) (or ARGUS_DASHBOARD=false). /metrics still serves.

Why don't I see per-guild numbers in Prometheus?

By design. guild_id/user_id/channel_id are unbounded and would explode Prometheus, so they are never labels (invariant 2). Per-guild figures live in the analytical path: set enable_per_guild=true + clickhouse_dsn, and use the dashboard's Analytics section. See History and ClickHouse.

discord_cached_users looks wrong / is zero

It reflects the cache, which needs the members intent enabled on your bot to be meaningful.

I run multiple processes (clustering)

Run one Argus per process with a distinct cluster_id; the cluster label separates them and counter rates aggregate across the fleet. See Clustering.

Can I host the dashboard/metrics completely separately from the bot?

The /metrics endpoint cannot be moved out of the bot process: gauges read live bot state at scrape time. So collection is always in-process. What you centralise is the view (Grafana, which aggregates all processes via Prometheus) and the storage (one shared ClickHouse for analytics). The built-in per-process dashboard is for a single process; use Grafana for a fleet view (set grafana_url).

100 clusters - should I use ports 9191..9290?

No. If each cluster is on its own host/container/pod (the normal case), keep the same port 9191 everywhere - they do not collide across hosts. Only co-located processes need distinct ports, and then assign them via ARGUS_PORT from your orchestrator and use Prometheus service discovery (Kubernetes PodMonitor, file_sd, DNS) instead of a hand-written 100-target scrape config. Full guidance: Clustering.

Does it slow my bot down?

No measurable amount. Hooks are O(1), non-blocking, and fail-open (an instrumentation error is counted and swallowed, never raised into your bot). The metrics server runs on the bot's existing loop.

How do I send metrics to Datadog / an OTLP collector?

pip install "argus-dpy[otlp]" and set otlp_endpoint. Argus pushes via OpenTelemetry in addition to the Prometheus endpoint. See OTLP.

Where do I get Grafana dashboards?

docker compose up -d in the repo brings up a provisioned Prometheus + Grafana with three dashboards. Point the dashboard's Grafana section at them with grafana_url.

Is the bundled image safe to deploy?

ghcr.io/astoristhebrave/argus:<version> ships the released SDK + the example bot. Pin a version tag so a mid-development change can never reach your deployment; :latest tracks the newest release. See Releasing.