astrae

Operations

Metrics API and dashboard

On by default at http://127.0.0.1:9100/. Loopback on purpose.

bot = Client(metrics_token="replace-me")
ASTRAE_METRICS_TOKEN=replace-me python bot.py

Configuration

Name Purpose
metrics=True Collection and HTTP service. Pass False to disable.
metrics_host Bind address. Default 127.0.0.1. ASTRAE_METRICS_HOST overrides.
metrics_port Default 9100. ASTRAE_METRICS_PORT overrides. Cluster ID may offset.
metrics_token Bearer for API and Prometheus. ASTRAE_METRICS_TOKEN overrides. HTML dashboard stays local.
Cluster 0 One dashboard. Other clusters publish expiring telemetry to Redis.
ASTRAE_METRICS_PER_CLUSTER Extra dashboards: cluster ID added to the base port.
pip install '.[metrics]' psutil for CPU/RSS. Without it those gauges are missing.
LoopMonitor On by default. Stalls go to logs, metrics, and the dashboard.

When a token is set:

Authorization: Bearer replace-me

Endpoints

Name Purpose
/ / /dashboard Live dashboard, refreshed every two seconds.
/dashboard/commands Live command logs across every cluster.
/dashboard/operations Commands, Discord requests, components, views, errors.
/dashboard/guilds Top guilds, member totals, shard state, guild lookup.
/api/v1 API metadata and endpoint discovery.
/api/health / /api/v1/health Fleet health: counts, latency, rates, per-cluster, per-shard.
/api/v1/metrics Self-describing metric catalog and current values.
/api/v1/dashboard Guild, member, and shard operational details.
/api/v1/dashboard/live Lightweight cluster, memory, shard, activity, and error state.
/api/v1/users/{user_id}/mutual-guilds Mutual guilds found in the member cache.
/metrics Prometheus text. Process-local. Scrape every process.

JSON snapshot fields

Name Purpose
generated_at Snapshot time.
summary.families / summary.series Counts in this snapshot.
metrics[].name Raw Prometheus name.
title / description / type / unit Human metadata.
labels Label meanings. Bounded categories only. No URLs, Discord IDs, or message text.
series Labeled current value plus bounded history.
statistics Histogram summary: count, sum, min, max. Not every sample.

Health fields

Name Purpose
users Global member total from gateway census.
user Connected bot account (name, avatar, banner) when known.
lib / version Library name and installed version.
avg_latency / latency Mean gateway round trip in milliseconds.
server_count Fleet guild total.
commands / command_count Registered commands and groups, excluding aliases.
commands_total Completed invocations.
gateway / cache Events and cache operations per second.
cache_hit Hit percentage.
cpu Process CPU percent across all cores. 100 means every core is busy.
memory Resident set size in mebibytes. Not the Python heap.
per_cluster Those stats per reporting process.
per_shard Guild, user, channel, role, latency, gateway rate, owner, ready, lifecycle.
history Latest 120 samples, about every five seconds. at is Unix ms.
Channel / role totals Guild payloads plus later create/delete events. Not a cache scan.

What else is measured

Name Purpose
Commands Invocations, outcome, source, duration.
Gateway dispatch Handler outcomes and time.
REST Count by method and outcome, plus duration. Route IDs become {id}.
Shards Known and ready counts.
Workers Queue depth and leased partitions.
Views Persistent and timed component views, plus component count.
Fleet RSS Sum of reporting clusters, plus per-cluster warmup memory.
Guild page Shared inventory: ownership, features, boost, channels, roles, emojis, stickers, cached members. IDs as strings.
Mutual guilds Complete only with member cache + warmup. Otherwise marked cached-only.
Warmup RSS, ceiling, cached members, pending chunks, paused flag.
GcFreezer Count, duration, permanent-generation objects, skipped while chunks fly.
Errors Latest 100 log records. Loop stalls include task stacks.
Activity Latest 250 per process, merged newest-first. No bodies, headers, query, or tokens.
Sentry / Tracelet Same errors and activity after setup_sentry() / setup_tracelet().

Scope

Name Purpose
In-process Metrics reset on restart. Not persisted.
Prometheus This process only.
Dashboard Merges expiring Redis telemetry when a shared cache is configured.
No Redis "scope":"process". Current process only.
Stopped cluster Expiring records disappear. No stale dashboard rows.
Bearer token Shared secret, not user auth. Do not publish the listener.