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)
host	ARGUS_HOST	str	0.0.0.0	bind host
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/*
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

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.

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.