Monitoring Endpoints

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

http_port: 8222

Or via command line:

nats-server -m 8222
# or
nats-server --http_port 8222

HTTPS Monitoring Port

https_port: 8443

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

Or via command line:

nats-server -ms 8443
# or
nats-server --https_port 8443

Custom Base Path

http_port: 8222
http_base_path: "/nats"

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

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

curl http://localhost:8222/varz

Response Schema

From server/monitor.go:1211-1283:

{
  "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

# 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

{
  "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

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

{
  "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

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

{
  "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

curl 'http://localhost:8222/subsz?test=orders.create'

Returns whether any subscriptions match the test subject.

/jsz - JetStream Information

JetStream metrics and status.

Request

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

{
  "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

curl http://localhost:8222/healthz

Response

Healthy (200 OK):

{"status": "ok"}

Unhealthy (503 Service Unavailable):

{"status": "unavailable", "error": "JetStream not ready"}

JetStream Health

Include JetStream in health check:

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.

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.

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.

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.

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.

curl http://localhost:8222/stacksz

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

Deadlocks
Performance bottlenecks
Goroutine leaks

Stack dumps can be large and may impact performance. Use only for debugging.

/raftz

Raft consensus group information (JetStream clustering).

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.

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

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:

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

scrape_configs:
  - job_name: 'nats'
    static_configs:
      - targets: ['localhost:7777']

Custom Prometheus Exporter

Poll /varz and /connz:

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:

# Bind to localhost only
nats-server --http_port localhost:8222

Or via configuration:

http: "localhost:8222"

2. Use HTTPS

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:

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

4. Firewall Rules

# 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

# 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.

​Monitoring Overview

​Enabling Monitoring

​HTTP Monitoring Port

​HTTPS Monitoring Port

​Custom Base Path