Wiki · Features in depth
Usage and monitoring
Monitoring is not about having a chart. It is about knowing before your users do — from /usage to your own supervision stack.
/usage), an installation overview
in the dashboard, and a machine-readable metrics export for the systems you already watch. Start with
the first one — it is free and immediate.1. What it costs: /usage and /insights
| Command | What it shows |
|---|---|
/usage | Token usage, cost breakdown (input/output), context window state, session duration and — when the provider supports it — remaining quota or credit |
/insights | Usage overview for the last 30 days: what was used and what it cost |
If the bill looks high, look at context size first, not at the price per token. Long sessions without cleanup are the most common reason an account grows faster than the work justifies.
2. Installation overview: the dashboard
The Status page refreshes every 5 seconds and shows:
| Item | Meaning |
|---|---|
| Version and release date | Which version you run (handy in a bug report) |
| Gateway status | Running/stopped, PID, connected platforms and their state |
| Active sessions | How many sessions were active in the last 5 minutes |
| Recent 20 sessions | Model, message count, token usage and a conversation preview |
3. Health from the command line: hermes doctor
The exit code turns doctor into a usable check for cron or CI: “if this fails, message me”.
It also checks the IPv6 route (a blackholed prefix is reported with the remedy
network.force_ipv4: true).
4. Machine-readable metrics (OTLP)
For real supervision — Prometheus, DataDog, an OpenTelemetry Collector — the gateway exports metrics, events and diagnostics over OTLP/HTTP:
| Signal | Contents |
|---|---|
| Metrics | hermes.gateway.up/state/busy/active_agents/background_work, platform state, cron ticker and job counts |
| Events (traces) | Gateway state transitions (starting → running → draining → stopped), platform changes, cron lifecycle |
| Diagnostics (logs) | Warnings and errors with a bounded error code and class — never prompt or message text |
The export is content-free by design: no prompts, messages, tool arguments, job names or session history. Nothing you entrusted to the agent reaches a third-party system — and you still learn that the gateway is down.
What to alert on
| Rule | Why |
|---|---|
hermes_gateway_up == 0 | The gateway is explicitly down (the process runs but does not report) |
| A missing series longer than the export interval | A process that died cannot emit its own zero — without this rule an outage goes unreported |
hermes.platform.degraded | A platform (Telegram, Discord) lost its connection while the gateway keeps running |
| Age of the last cron success | A scheduled job stopped running — more common than a dead gateway |
The second rule comes from our own operations: a metric that only says “I am OK” looks like calm during an outage. Always monitor that the data stopped arriving, too.
Things to watch
| Situation | What to do |
|---|---|
| The OTLP SDK is missing | It installs on first use (the otlp extra); without it the gateway runs fine, it just does not export |
| The endpoint is unreachable | Export must never take the agent down — failures are bounded and stay off the hot path |
| The dashboard warns about memory | Shorten sessions, reduce parallel subagents, add RAM; the banner clears after a gateway restart |
| High token usage | Shorter sessions, a cheaper model for auxiliary tasks (e.g. the curator), fewer tools in context |
| You have monitoring but nobody looks | Set a threshold that sends a Telegram message — a chart nobody visits is not monitoring |