nself monitor

Toggle the full observability stack — Prometheus, Grafana, Loki, and 7 more services — and open the dashboard in one command.

Quick start

# Start the monitoring stack
nself monitor start

# Open Grafana in your browser
nself monitor dashboard

# Check which monitoring services are running
nself monitor status

# Stop the monitoring stack (preserves data)
nself monitor stop

Synopsis

nself monitor <SUBCOMMAND> [FLAGS]

Description

nself monitor manages the optional 10-service monitoring bundle that ships with every ɳSelf stack. The bundle is off by default in development (too heavy for laptop use) and enabled by default in staging and production. You can toggle it independently of the core stack.

All monitoring services bind to 127.0.0.1 and are accessible through your nginx proxy at their configured subdomains (e.g. grafana.local.nself.org in dev,grafana.yourdomain.com in production). No monitoring port is exposed directly to the internet.

Prometheus scrapes metrics from all running ɳSelf services automatically — no manual configuration needed. Grafana ships with pre-built dashboards for Postgres, Hasura, auth, nginx, and your custom services. Loki collects all container logs and makes them searchable in Grafana's Explore view.

Monitoring bundle services

Subcommands

nself monitor start

Start all 10 monitoring services. If the core stack is not running, ɳSelf starts it first.

nself monitor start
nself monitor start --lite        # dev-friendly: Prometheus + Grafana + Node Exporter only
nself monitor start --no-tempo    # skip tracing to save memory

nself monitor stop

Stop the monitoring stack. Core services (Postgres, Hasura, Auth, Nginx) continue running. Prometheus data is preserved in its Docker volume.

nself monitor stop

nself monitor status

Print the health of each monitoring service: running, stopped, or degraded.

nself monitor status
# SERVICE              STATUS    UPTIME      MEMORY
# prometheus           running   2h 14m      128 MB
# grafana              running   2h 14m      94 MB
# loki                 running   2h 14m      189 MB
# promtail             running   2h 14m      22 MB
# tempo                running   2h 14m      156 MB
# alertmanager         running   2h 14m      18 MB
# cadvisor             running   2h 14m      42 MB
# node-exporter        running   2h 14m      12 MB
# postgres-exporter    running   2h 14m      14 MB
# redis-exporter       stopped   —           — (Redis not enabled)

nself monitor dashboard

Open the Grafana dashboard in your default browser. Grafana must be running (start it with nself monitor start first).

nself monitor dashboard
nself monitor dashboard --service postgres
nself monitor dashboard --service logs      # opens Loki Explore view
nself monitor dashboard --url               # print URL for remote access

Pre-built Grafana dashboards

Alertmanager configuration

Alert routing rules live in backend/monitoring/alertmanager.yml. This file is hand-managed (not regenerated by nself build).

# Example: route critical alerts to Slack
backend/monitoring/
  alertmanager.yml    ← edit for your alert receivers
  rules/
    postgres.yml      ← pre-built alert rules
    hasura.yml
    system.yml

Examples

Start monitoring on a new staging deployment

nself start
nself monitor start
nself monitor status
nself monitor dashboard --url

Lightweight dev monitoring

# Use --lite to avoid 700 MB of extra containers during development
nself monitor start --lite
nself monitor dashboard --service system

Check for Postgres slow queries

nself monitor dashboard --service postgres
# → Opens the Postgres dashboard filtered to queries > 100ms

Environment variables

• ENABLE_MONITORING — set to true to start monitoring automatically with nself start (default: false in dev, true in staging/prod)
• GRAFANA_ADMIN_PASSWORD — Grafana admin password (default: admin in dev; must be set in prod)
• PROMETHEUS_RETENTION — how long to keep metrics data (default: 15d)

Exit codes

• 0 — success
• 1 — one or more services failed to start
• 2 — invalid arguments
• 3 — core stack not running (start with nself start first)

Related

• nself logs — tail container logs directly (without Loki)
• nself alerts — manage Prometheus alert rules and notification channels
• nself status — quick health check without launching Grafana