Metrics and monitoring

Prometheus metrics, the bundled Prometheus container, and the health endpoint to point your uptime monitor at.

Last updated Aug 14, 2026View as Markdown

Overview

The panel exposes Prometheus metrics under the nasnet_ namespace, and the Docker Compose stack ships a Prometheus container already wired to scrape it. That gives you real observability out of the box: HTTP latency, host CPU and memory, traffic and online users, certificate expiry per domain, database pool usage and scheduler timings, all of them queryable and all a natural Grafana data source.

Before you start

  • Protect the metrics endpoint before you expose it. METRICS_USERNAME and METRICS_PASSWORD add basic auth, and the bundled Prometheus is wired to use them when they are set.
  • Metrics collection can be toggled without a restart from Settings → Server → Monitoring; the collector re-reads the metrics_enabled database setting on every scheduler tick. The METRICS_ENABLED environment variable is only the startup default.

Steps

  1. Set the metrics keys in .env:

    METRICS_ENABLED=true
METRICS_PATH=/metrics
METRICS_USERNAME=prometheus
METRICS_PASSWORD=change-me

  2. Under Docker Compose, the bundled Prometheus comes up with the stack on ${PROMETHEUS_PORT:-9090} and scrapes the app automatically.

  3. Point Grafana at that Prometheus to build dashboards.

  4. Point your uptime monitor or load balancer at the readiness probe:

    curl -f http://localhost:9761/health/ready

Reference

Metric group Examples
HTTP Request totals, latency histogram, in-flight requests.
Business Users, subscriptions.
Server (Xray and host) Host CPU, memory and disk; active connections, traffic, online users, Xray core uptime.
Provisioning Queue depth, tasks processed with success and failure counts.
Certificates Seconds until expiry, per domain.
Database Connection-pool usage.
Scheduler Per-task duration and error counts.
Event bus Events published, active subscribers.
Variable What it does Default
METRICS_ENABLED Startup default for collection. true
METRICS_PATH Where metrics are served. /metrics
METRICS_USERNAME Basic-auth user for the metrics endpoint. empty
METRICS_PASSWORD Basic-auth password. empty
PROMETHEUS_PORT Host port for the bundled Prometheus. Compose only. 9090
PROMETHEUS_RETENTION How long Prometheus keeps series. Compose only. 15d
PROMETHEUS_SCRAPE_INTERVAL Scrape interval. Compose only. 5s
PROMETHEUS_TARGET What Prometheus scrapes. Compose only. app:9761

Notifications for events and alerts are dispatched separately, through the Telegram, Discord and webhook channels configured under Settings → Notifications. The event matrix there lets you pick, per channel, which events notify, covering server online and offline, Xray down, recovered and crash loop, subscription created, renewed, cancelled and expired, and system alerts among them.