# Metrics and monitoring

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

Source: https://joinnasnet.com/en/guides/nasnet-linux/monitoring/
Last updated: 2026-08-14

---

## 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`:

   ```dotenv
   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:

   ```bash
   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.

## Related

- [Alerts](/en/guides/nasnet-linux/alerts/)
- [Settings](/en/guides/nasnet-linux/settings/)
- [Dashboard](/en/guides/nasnet-linux/dashboard/)