> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring Endpoints

> HTTP monitoring endpoints for NATS Server metrics and status

## Monitoring Overview

NATS Server exposes HTTP endpoints for monitoring server health, performance, and operational metrics. These endpoints are essential for observability in production deployments.

## Enabling Monitoring

### HTTP Monitoring Port

```hocon theme={null}
http_port: 8222
```

Or via command line:

```bash theme={null}
nats-server -m 8222
# or
nats-server --http_port 8222
```

### HTTPS Monitoring Port

```hocon theme={null}
https_port: 8443

http {
  tls {
    cert_file: "/path/to/monitor-cert.pem"
    key_file: "/path/to/monitor-key.pem"
  }
}
```

Or via command line:

```bash theme={null}
nats-server -ms 8443
# or
nats-server --https_port 8443
```

### Custom Base Path

```hocon theme={null}
http_port: 8222
http_base_path: "/nats"
```

Endpoints available at: `http://localhost:8222/nats/varz`

## Monitoring Endpoints

From server/server.go:3037-3046, available endpoints:

* `/varz` - General server information
* `/connz` - Connection information
* `/routez` - Route information
* `/subsz` - Subscription information
* `/jsz` - JetStream information
* `/healthz` - Health check
* `/` - Endpoint index

## /varz - Server Information

General server metrics and configuration.

### Request

```bash theme={null}
curl http://localhost:8222/varz
```

### Response Schema

From server/monitor.go:1211-1283:

```json theme={null}
{
  "server_id": "NDJWE4VIYOFR2XQGVQFVXR2VUAA2AKLGZQMXQZ7JY7YL4YQZQTQJQQ",
  "server_name": "nats-1",
  "version": "2.10.0",
  "proto": 1,
  "git_commit": "abc1234",
  "go": "go1.21.5",
  "host": "0.0.0.0",
  "port": 4222,
  "auth_required": true,
  "tls_required": true,
  "tls_verify": true,
  "max_connections": 65536,
  "max_subscriptions": 0,
  "ping_interval": 120000000000,
  "ping_max": 2,
  "http_host": "0.0.0.0",
  "http_port": 8222,
  "https_port": 0,
  "auth_timeout": 1,
  "max_control_line": 4096,
  "max_payload": 1048576,
  "max_pending": 67108864,
  "tls_timeout": 0.5,
  "write_deadline": 10000000000,
  "start": "2026-03-04T10:15:30.123456Z",
  "now": "2026-03-04T11:20:15.789012Z",
  "uptime": "1h4m45s",
  "mem": 12582912,
  "cores": 8,
  "gomaxprocs": 8,
  "cpu": 2.5,
  "connections": 142,
  "total_connections": 1523,
  "routes": 2,
  "remotes": 2,
  "leafnodes": 5,
  "in_msgs": 5234567,
  "out_msgs": 5234123,
  "in_bytes": 1048576000,
  "out_bytes": 1048500000,
  "slow_consumers": 3,
  "stale_connections": 12,
  "stalled_clients": 0,
  "subscriptions": 1543,
  "http_req_stats": {
    "/varz": 523,
    "/connz": 142,
    "/healthz": 10234
  },
  "config_load_time": "2026-03-04T10:15:29.123456Z",
  "tls_cert_not_after": "2027-03-04T10:15:29.123456Z"
}
```

### Key Metrics

**Performance:**

* `cpu` - Current CPU usage percentage
* `mem` - Current memory usage in bytes
* `connections` - Active connections
* `in_msgs` / `out_msgs` - Message counts
* `in_bytes` / `out_bytes` - Data transfer

**Health:**

* `slow_consumers` - Slow consumer disconnections
* `stale_connections` - Stale connection count
* `uptime` - Server uptime

**Configuration:**

* `max_connections` - Connection limit
* `max_payload` - Maximum message size
* `tls_required` - TLS enforcement

## /connz - Connection Information

Detailed information about client connections.

### Request

```bash theme={null}
# All connections
curl http://localhost:8222/connz

# With query parameters
curl 'http://localhost:8222/connz?auth=true&subs=true&offset=0&limit=10'
```

### Query Parameters

From server/monitor.go:58-99:

* `sort` - Sort by: `cid`, `start`, `subs`, `pending`, `msgs_to`, `msgs_from`, `bytes_to`, `bytes_from`, `last`, `idle`, `uptime`, `stop`, `reason`, `rtt`
* `auth` - Include username (default: false)
* `subs` - Include subscriptions (default: false)
* `offset` - Pagination offset (default: 0)
* `limit` - Pagination limit (default: 1024)
* `cid` - Filter by connection ID
* `state` - Filter by state: `open`, `closed`, `all`
* `user` - Filter by username
* `acc` - Filter by account
* `mqtt_client` - Filter by MQTT client ID

### Response Schema

```json theme={null}
{
  "server_id": "NDJWE4VIYOFR2XQGVQFVXR2VUAA2AKLGZQMXQZ7JY7YL4YQZQTQJQQ",
  "now": "2026-03-04T11:20:15.789012Z",
  "num_connections": 10,
  "total": 142,
  "offset": 0,
  "limit": 10,
  "connections": [
    {
      "cid": 1,
      "kind": "Client",
      "type": "nats",
      "ip": "127.0.0.1",
      "port": 52461,
      "start": "2026-03-04T10:15:35.123456Z",
      "last_activity": "2026-03-04T11:20:14.987654Z",
      "rtt": "245µs",
      "uptime": "1h4m39s",
      "idle": "1s",
      "pending_bytes": 0,
      "in_msgs": 12534,
      "out_msgs": 12532,
      "in_bytes": 2506800,
      "out_bytes": 2506400,
      "subscriptions": 5,
      "name": "order-service",
      "lang": "go",
      "version": "1.31.0",
      "tls_version": "1.3",
      "tls_cipher_suite": "TLS_AES_256_GCM_SHA384",
      "authorized_user": "alice",
      "account": "PRODUCTION",
      "subscriptions_list": ["orders.>", "_INBOX.abc123"]
    }
  ]
}
```

### Connection States

* `open` - Active connections
* `closed` - Recently closed connections (configurable retention)
* `all` - Both open and closed

### Sorting Options

From server/monitor.go:501-528, all descending except `cid`:

* `ByCid` - By connection ID (ascending)
* `BySubs` - By subscription count
* `ByPending` - By pending bytes
* `ByOutMsgs` - By messages sent
* `ByInMsgs` - By messages received
* `ByOutBytes` - By bytes sent
* `ByInBytes` - By bytes received
* `ByLast` - By last activity
* `ByIdle` - By idle time
* `ByUptime` - By connection duration
* `ByRTT` - By round-trip time

## /routez - Route Information

Information about cluster routes.

### Request

```bash theme={null}
curl http://localhost:8222/routez

# With subscriptions
curl 'http://localhost:8222/routez?subs=true'
```

### Query Parameters

* `subs` - Include subscriptions (default: false)
* `subs=detail` - Include detailed subscription info

### Response Schema

```json theme={null}
{
  "server_id": "NDJWE4VIYOFR2XQGVQFVXR2VUAA2AKLGZQMXQZ7JY7YL4YQZQTQJQQ",
  "server_name": "nats-1",
  "now": "2026-03-04T11:20:15.789012Z",
  "num_routes": 2,
  "routes": [
    {
      "rid": 1,
      "remote_id": "NDABC...",
      "remote_name": "nats-2",
      "did_solicit": true,
      "ip": "10.0.1.2",
      "port": 6222,
      "start": "2026-03-04T10:15:35.123456Z",
      "last_activity": "2026-03-04T11:20:14.987654Z",
      "rtt": "1.2ms",
      "uptime": "1h4m39s",
      "idle": "1s",
      "in_msgs": 52341,
      "out_msgs": 52338,
      "in_bytes": 10468200,
      "out_bytes": 10467600,
      "subscriptions": 1543
    }
  ]
}
```

## /subsz - Subscription Information

Detailed subscription statistics.

### Request

```bash theme={null}
curl http://localhost:8222/subsz

# Filter by subject
curl 'http://localhost:8222/subsz?subject=orders.>'
```

### Query Parameters

* `subject` - Filter by subject pattern
* `test` - Test if subject matches any subscription

### Response Schema

```json theme={null}
{
  "server_id": "NDJWE4VIYOFR2XQGVQFVXR2VUAA2AKLGZQMXQZ7JY7YL4YQZQTQJQQ",
  "now": "2026-03-04T11:20:15.789012Z",
  "num_subscriptions": 1543,
  "num_cache": 512,
  "num_inserts": 5234,
  "num_removes": 3691,
  "num_matches": 52341234,
  "cache_hit_rate": 98.5,
  "max_fanout": 42,
  "avg_fanout": 3.2
}
```

### Subscription Test

```bash theme={null}
curl 'http://localhost:8222/subsz?test=orders.create'
```

Returns whether any subscriptions match the test subject.

## /jsz - JetStream Information

JetStream metrics and status.

### Request

```bash theme={null}
curl http://localhost:8222/jsz

# Detailed account info
curl 'http://localhost:8222/jsz?accounts=true&streams=true&consumers=true'
```

### Query Parameters

* `accounts` - Include account details
* `streams` - Include stream details
* `consumers` - Include consumer details
* `config` - Include configuration
* `leader-only` - Only respond if leader
* `offset` - Pagination offset
* `limit` - Pagination limit

### Response Schema

```json theme={null}
{
  "server_id": "NDJWE4VIYOFR2XQGVQFVXR2VUAA2AKLGZQMXQZ7JY7YL4YQZQTQJQQ",
  "now": "2026-03-04T11:20:15.789012Z",
  "config": {
    "max_memory": 1073741824,
    "max_storage": 10737418240,
    "store_dir": "/data/jetstream"
  },
  "stats": {
    "memory": 104857600,
    "storage": 524288000,
    "reserved_memory": 0,
    "reserved_storage": 0,
    "accounts": 3,
    "ha_assets": 5,
    "api": {
      "total": 52341,
      "errors": 12
    }
  },
  "meta": {
    "name": "production",
    "leader": "nats-1",
    "peer": "NDJWE...",
    "peers": [
      {
        "name": "nats-1",
        "current": true,
        "offline": false,
        "active": "1.2s",
        "lag": 0
      },
      {
        "name": "nats-2",
        "current": true,
        "offline": false,
        "active": "890ms",
        "lag": 0
      }
    ],
    "cluster_size": 3
  }
}
```

## /healthz - Health Check

Simple health check endpoint.

### Request

```bash theme={null}
curl http://localhost:8222/healthz
```

### Response

**Healthy (200 OK):**

```json theme={null}
{"status": "ok"}
```

**Unhealthy (503 Service Unavailable):**

```json theme={null}
{"status": "unavailable", "error": "JetStream not ready"}
```

### JetStream Health

Include JetStream in health check:

```bash theme={null}
curl 'http://localhost:8222/healthz?js-enabled-only=true'
```

Returns 503 if JetStream is not enabled or unhealthy.

## Additional Monitoring Endpoints

### /gatewayz

Gateway connections and statistics.

```bash theme={null}
curl http://localhost:8222/gatewayz
```

Returns information about gateway connections between clusters including:

* Gateway names and remote cluster connections
* Inbound and outbound connections
* Message counts and bytes transferred
* Account information per gateway

### /leafz

Leaf node connections monitoring.

```bash theme={null}
curl http://localhost:8222/leafz
```

Displays leaf node connections:

* Leaf node account bindings
* Connection state and RTT
* Subscription count
* Bytes in/out

### /accountz

Account-level statistics.

```bash theme={null}
curl http://localhost:8222/accountz?acc=ACCOUNT_NAME
```

Query parameters:

* `acc` - Account name to query (optional, returns all if omitted)

Returns account details:

* Connection count per account
* Subscriptions and slow consumers
* Sent/received messages and bytes
* JetStream usage if enabled

### /accountstatz

Detailed account statistics over time.

```bash theme={null}
curl http://localhost:8222/accountstatz
```

Provides time-series statistics for accounts including:

* Historical connection counts
* Message rate trends
* Byte transfer rates
* Resource usage patterns

### /stacksz

Server stack traces for debugging.

```bash theme={null}
curl http://localhost:8222/stacksz
```

Returns Go runtime stack traces for all goroutines. Useful for debugging:

* Deadlocks
* Performance bottlenecks
* Goroutine leaks

<Warning>
  Stack dumps can be large and may impact performance. Use only for debugging.
</Warning>

### /raftz

Raft consensus group information (JetStream clustering).

```bash theme={null}
curl http://localhost:8222/raftz
```

Shows Raft group details:

* Leader and follower information
* Log indexes and terms
* Peer states
* Stream and consumer assignments

### /ipqueuesz

IP-based connection queue statistics.

```bash theme={null}
curl http://localhost:8222/ipqueuesz
```

Monitors connection queues per IP address:

* Pending connections per IP
* Queue depths
* Connection throttling status

## Endpoint Index

Root monitoring endpoint lists available endpoints.

### Request

```bash theme={null}
curl http://localhost:8222/
```

### Response

HTML page with links to all monitoring endpoints.

## Prometheus Integration

NATS Server monitoring endpoints are compatible with Prometheus.

### Using nats-surveyor

The official Prometheus exporter:

```bash theme={null}
# Install nats-surveyor
go install github.com/nats-io/nats-surveyor@latest

# Run exporter
nats-surveyor -s nats://localhost:4222 -http_port 7777
```

Scrape configuration:

```yaml theme={null}
scrape_configs:
  - job_name: 'nats'
    static_configs:
      - targets: ['localhost:7777']
```

### Custom Prometheus Exporter

Poll `/varz` and `/connz`:

```python theme={null}
import requests
from prometheus_client import Gauge

varz_gauge = Gauge('nats_connections', 'NATS connections')

def collect_metrics():
    resp = requests.get('http://localhost:8222/varz')
    data = resp.json()
    varz_gauge.set(data['connections'])
```

## Security Considerations

### 1. Restrict Access

Monitoring endpoints expose sensitive information:

```bash theme={null}
# Bind to localhost only
nats-server --http_port localhost:8222
```

Or via configuration:

```hocon theme={null}
http: "localhost:8222"
```

### 2. Use HTTPS

```hocon theme={null}
https_port: 8443
http {
  tls {
    cert_file: "/path/to/cert.pem"
    key_file: "/path/to/key.pem"
  }
}
```

### 3. Reverse Proxy with Auth

Use nginx or similar:

```nginx theme={null}
location /nats/ {
    auth_basic "NATS Monitoring";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://localhost:8222/;
}
```

### 4. Firewall Rules

```bash theme={null}
# Allow only from monitoring server
iptables -A INPUT -p tcp --dport 8222 -s 10.0.1.10 -j ACCEPT
iptables -A INPUT -p tcp --dport 8222 -j DROP
```

## Monitoring Best Practices

### 1. Regular Health Checks

```bash theme={null}
# Add to monitoring system
curl -f http://localhost:8222/healthz || alert
```

### 2. Track Key Metrics

Monitor:

* Connection count
* Message rates
* Slow consumers
* Memory usage
* CPU usage

### 3. Set Up Alerts

* Slow consumer rate > threshold
* Memory usage > 80%
* Connection failures
* JetStream disk usage > 90%

### 4. Centralized Monitoring

Integrate with:

* Prometheus + Grafana
* Datadog
* New Relic
* CloudWatch

### 5. Monitor Endpoints Performance

From `/varz`, check `http_req_stats` for endpoint usage.

## Related Topics

* [Logging Configuration](/operations/logging)
* [Security Overview](/operations/security)