How to Monitor Nginx Unit with Vigilmon (HTTP, TCP, and SSL Alerts)

Nginx Unit is a dynamic, polyglot application server from the Nginx team — a modern alternative to Gunicorn, uWSGI, and PHP-FPM that can run Python, Go, PHP, Node.js, Ruby, Java, and WebAssembly applications side by side under a single process. Its runtime reconfiguration via a control API is powerful, but also means Unit can silently drop application listeners or misconfigure itself during live updates without surfacing an obvious error.

In this tutorial you'll set up end-to-end monitoring for Nginx Unit using Vigilmon — free tier, no credit card.

Why Nginx Unit needs dedicated monitoring

Nginx Unit's architecture introduces failure modes that are easy to miss:

• Silent listener removal — a unitd configuration update that fails validation rolls back silently; if you're not watching the listeners, an application may stop accepting connections while the control socket stays healthy
• Application process crash — an individual language runtime (Python worker, Node.js process) can crash and not be respawned if the restart limit is hit, leaving the listener bound but returning 502s for every request
• Control API socket unreachable — the Unix domain socket used for configuration becomes inaccessible after a permissions change or daemon restart, blocking all future configuration changes
• Listener port conflict — another service grabs the port Unit is supposed to listen on; Unit logs an error at startup and skips that listener without aborting

Monitoring both the application-facing HTTP ports and the Unit control API status endpoint gives you full coverage of these failure modes.

What you'll need

• Nginx Unit installed and configured (version 1.29+)
• At least one application listener configured in Unit
• A public URL or Vigilmon agent for private network access
• A free Vigilmon account (sign up takes 30 seconds)

Step 1: Verify the Nginx Unit status endpoint

Nginx Unit's control API exposes a /status endpoint that reports application and connection statistics. By default the control socket is a Unix domain socket, but you can also expose it over TCP for remote monitoring.

Option A: Unix socket (local only)

curl --unix-socket /run/control.unit.sock http://localhost/status

Option B: TCP control socket (for remote monitoring)

Add a listener to Unit's configuration that exposes the control API on a local TCP port:

{
  "listeners": {
    "127.0.0.1:8085": {
      "pass": "routes/status"
    }
  },
  "routes": {
    "status": [
      {
        "action": {
          "proxy": "http://unix:/run/control.unit.sock:/status"
        }
      }
    ]
  }
}

Apply this configuration:

curl -X PUT --data-binary @status-route.json \
  --unix-socket /run/control.unit.sock \
  http://localhost/config

Now test the status endpoint:

curl http://127.0.0.1:8085/status

Expected response:

{
  "connections": {
    "accepted": 1024,
    "active": 3,
    "idle": 10,
    "closed": 1011
  },
  "requests": {
    "total": 2048
  },
  "applications": {
    "my-python-app": {
      "processes": {
        "running": 4,
        "starting": 0,
        "idle": 2
      },
      "requests": {
        "active": 1
      }
    }
  }
}

Step 2: Add a health endpoint to your application

Unit itself has a /status API, but you'll also want each application to expose its own health route so Vigilmon can verify the application layer — not just the server layer.

Python (Flask):

@app.route('/health')
def health():
    return {'status': 'ok'}, 200

Node.js (Express):

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

Go:

http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"status":"ok"}`))
})

Step 3: Set up HTTP monitoring for your application

1. Log in to vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS as the type
3. Set the URL to your application's health endpoint: https://your-app.example.com/health
4. Set the check interval to 1 minute
5. Under Expected response:
   • Status code: 200
   • Response body contains: "status":"ok"
6. Save the monitor

This monitors the full request path: DNS → TCP → TLS → Nginx Unit listener → application process → response.

Step 4: Monitor the Unit control API status

Set up a second monitor for the Unit status endpoint to catch server-level failures independently of your application:

1. Monitors → New Monitor → HTTP / HTTPS
2. URL: http://your-unit-host:8085/status (the proxied status endpoint from Step 1)
3. Expected status code: 200
4. Response body contains: "connections"
5. Save the monitor

If Unit crashes or the status proxy stops responding, this monitor fires before your application health check would.

Step 5: Set up TCP port monitoring for application listeners

TCP port monitoring is essential for Unit because it verifies that the listener port is actually bound — something that Unit's configuration API does not guarantee if a startup error skipped binding that port.

For each application listener port, create a TCP monitor:

1. Monitors → New Monitor → TCP Port
2. Hostname: your-unit-host
3. Port: 8080 (or whichever port your Unit listener uses)
4. Save the monitor

If you have multiple applications on multiple ports, add a TCP monitor for each one. A TCP failure means the listener was never bound or the Unit daemon has crashed.

Step 6: Enable SSL certificate monitoring

If Unit is deployed behind an Nginx or Caddy reverse proxy that terminates TLS — or if you configure Unit's built-in TLS listener — Vigilmon automatically monitors SSL certificate expiry for any HTTPS monitor.

1. Open your application HTTP monitor (from Step 3) in Vigilmon
2. Go to the SSL tab
3. Set the Alert before expiry threshold (e.g., 30 days)

Vigilmon will alert you before certificate expiry causes connections to fail.

If Unit handles TLS directly, check that your certificate and key are loaded in Unit's configuration:

curl --unix-socket /run/control.unit.sock http://localhost/certificates

Summary: Vigilmon monitors for Nginx Unit

| Monitor | Type | What it catches | |---------|------|-----------------| | https://your-app.example.com/health | HTTP | Application crash, 502 from dead workers, routing failures | | unit-host:8085/status | HTTP | Unit daemon failure, control API down | | unit-host:8080 | TCP | Listener port not bound, Unit startup failure | | SSL certificate | SSL | TLS cert expiry before connections break |

What's next

• Multiple application monitoring — Nginx Unit can serve many applications simultaneously; create a Vigilmon monitor group to track all listener ports in one dashboard
• Heartbeat monitoring — if you use Unit to serve background workers or scheduled task processors, add a heartbeat monitor so Vigilmon alerts you when those jobs stop completing
• Alert routing — connect Vigilmon to Slack, PagerDuty, or email so the right person is notified when a specific application listener goes down

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.