Configuration

Configuration

All configuration flows through one immutable ArgusConfig (invariant 6). Precedence is constructor kwargs > ARGUS_* environment variables > defaults. A kwarg left as None is treated as "not provided" and falls through to the environment, then the default.

Argus(bot, port=9300, cluster_id="eu-1", dashboard_auth_token="secret")

from argus import ArgusConfig
cfg = ArgusConfig.resolve(port=9300, environ={"ARGUS_NAMESPACE": "bot"})

Fields

kwarg	env	type	default	meaning
port	ARGUS_PORT	int	9191	server port (metrics + dashboard); falls back to SERVER_PORT (Pterodactyl/PebbleHost) then PORT (Railway/PaaS) before the default
host	ARGUS_HOST	str	0.0.0.0	bind host; falls back to SERVER_IP
metrics_path	ARGUS_METRICS_PATH	str	/metrics	metrics endpoint (leading slash enforced)
cluster_id	ARGUS_CLUSTER_ID	str	None -> default	value of the cluster label
namespace	ARGUS_NAMESPACE	str	discord	metric name prefix (argus_* internals excluded)
dashboard	ARGUS_DASHBOARD	bool	True	serve the SPA
dashboard_path	ARGUS_DASHBOARD_PATH	str	/	dashboard mount (must differ from metrics_path)
dashboard_interval	ARGUS_DASHBOARD_INTERVAL	int	5	seconds between SSE snapshots
dashboard_auth_token	ARGUS_DASHBOARD_AUTH_TOKEN	str	None	bearer token gating dashboard + /api/*
metrics_auth_token	ARGUS_METRICS_AUTH_TOKEN	str	None	bearer token gating /metrics itself (shared-host public binds)
log_format	ARGUS_LOG_FORMAT	str	text	json for structured logs on the argus logger
grafana_url	ARGUS_GRAFANA_URL	str	None	base URL for the Grafana section
enable_per_guild	ARGUS_ENABLE_PER_GUILD	bool	False	enable the analytical path
clickhouse_dsn	ARGUS_CLICKHOUSE_DSN	str	None	ClickHouse DSN for the sink + queries
otlp_endpoint	ARGUS_OTLP_ENDPOINT	str	None	OTLP collector endpoint (metrics)
enable_tracing	ARGUS_ENABLE_TRACING	bool	False	emit an OTLP span per command/interaction lifecycle (needs the otlp extra)
tracing_endpoint	ARGUS_TRACING_ENDPOINT	str	None	OTLP traces endpoint; falls back to otlp_endpoint
pushgateway_url	ARGUS_PUSHGATEWAY_URL	str	None	Prometheus Pushgateway URL (additive push; no inbound port)
pushgateway_job	ARGUS_PUSHGATEWAY_JOB	str	argus	job label for the Pushgateway push
pushgateway_interval	ARGUS_PUSHGATEWAY_INTERVAL	int	15	seconds between Pushgateway pushes
pushgateway_username / pushgateway_password	ARGUS_PUSHGATEWAY_USERNAME / _PASSWORD	str	None	optional HTTP basic auth for the Pushgateway

Fleet (member opt-in)

These wire a bot into a Fleet control plane. When fleet_url is unset, no fleet code runs at all - behaviour is exactly as without them. (The control plane's own server settings are separate; see Fleet.)

kwarg	env	type	default	meaning
fleet_url	ARGUS_FLEET_URL	str	None	opt in; register + heartbeat to this control plane
fleet_token	ARGUS_FLEET_TOKEN	str	None	shared (or ingest) token the bot presents
fleet_group	ARGUS_FLEET_GROUP	str	default	the region/fleet this process belongs to
fleet_id	ARGUS_FLEET_ID	str	None	stable identity; an auto-UUID is persisted if unset
fleet_state_dir	ARGUS_FLEET_STATE_DIR	str	.	where the auto-UUID identity is persisted
fleet_scrape_target	ARGUS_FLEET_SCRAPE_TARGET	str	None	advertise host:port for Prometheus http_sd

Parsing rules

• bool env values: 1/true/yes/on -> True, 0/false/no/off/"" -> False (case-insensitive); anything else raises ValueError.
• int env values go through int().
• metrics_path and dashboard_path are normalised to a leading /.
• cluster_id resolves to the literal string default when unset; that is the value emitted on the cluster label.

Dashboard auth token (minimal setup)

Set one environment variable on the host/process running the bot:

ARGUS_DASHBOARD_AUTH_TOKEN=your-secret

Argus reads it automatically and uses it to gate / and /api/* (the metrics and health endpoints stay open). The dashboard is served by Argus in the same process, so there is nothing else to configure or host. Viewers open http://host:9191/?token=your-secret once; the token is remembered in the browser. See the FAQ and Dashboard.

Notes

• ArgusConfig is a frozen, slotted dataclass; mutating it raises.
• resolve(environ=...) accepts an explicit mapping for testing/isolation.
• The dashboard and analytics interact: the per-guild analytics API only mounts when enable_per_guild and a clickhouse_dsn are set, and it refuses to serve without a dashboard_auth_token (fail-closed). See Dashboard.