Monitoring OpenResty with Vigilmon

OpenResty is a high-performance web platform built on Nginx with LuaJIT scripting. It's the foundation for API gateways, WAFs, and dynamic web applications that need sub-millisecond request processing with programmable logic. But OpenResty's power comes with operational complexity: Lua modules, shared memory dictionaries, upstream connection pools, and WAF rule processing can all fail independently while Nginx continues to accept connections. Vigilmon gives you layered monitoring from the TCP port through the Lua runtime so you catch failures at the layer where they actually occur.

What You'll Set Up

• HTTP uptime monitor for OpenResty on ports 80 and 443
• SSL/TLS certificate expiry alerts
• Nginx worker process health via the stub status module
• Lua runtime and shared memory dict health endpoint
• Upstream connection pool monitoring
• Rate limiter and WAF health verification

Prerequisites

• OpenResty installed and serving traffic on port 80/443
• ngx_http_stub_status_module enabled (included in OpenResty by default)
• A custom Lua health endpoint (we'll add one in Step 3)
• A free Vigilmon account

Step 1: Monitor HTTP and HTTPS Availability

The first layer of OpenResty monitoring is confirming the HTTP and HTTPS listeners are accepting connections and returning valid responses.

HTTP monitor:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: http://your-openresty-host
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200 (or 301 if you redirect HTTP to HTTPS).
6. Click Save.

HTTPS monitor:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: https://your-openresty-host
3. Set Expected HTTP status to 200.
4. Enable Monitor SSL certificate.
5. Set Alert when certificate expires in less than 21 days.
6. Click Save.

For API gateway deployments where the root path returns 404, use a known-good endpoint like https://your-openresty-host/health (which we'll configure in Step 3).

Step 2: SSL/TLS Certificate Expiry Monitoring

OpenResty commonly terminates SSL for multiple domains. A certificate expiring on any domain causes browser warnings and API failures for clients using that domain.

For each domain you serve:

1. Open Add Monitor → HTTP / HTTPS.
2. Enter the domain URL: https://api.example.com
3. Enable Monitor SSL certificate.
4. Set Alert threshold to 21 days.
5. Click Save.

List your domains in your Nginx config to make sure you cover them all:

grep -r "server_name" /usr/local/openresty/nginx/conf/ | grep -v "#"

Add one Vigilmon SSL monitor per unique domain. For wildcard certificates (*.example.com), one monitor on any subdomain covers the certificate, but you should still monitor each subdomain's HTTP availability separately since a subdomain can go down independently of the certificate.

Step 3: Add a Lua Health Endpoint

Add a Lua-based health endpoint to OpenResty that checks the Lua runtime, shared memory dictionaries, and module availability. This gives Vigilmon a rich signal beyond "is Nginx accepting connections."

In your OpenResty Nginx config (/usr/local/openresty/nginx/conf/nginx.conf or a site config):

server {
    listen 80;
    # ... your existing config ...

    location /health {
        access_log off;
        content_by_lua_block {
            local health = { status = "ok", checks = {} }

            -- Check shared memory dict
            local ok, err = pcall(function()
                local cache = ngx.shared.my_cache
                if cache then
                    local free_space = cache:free_space()
                    health.checks.shared_dict = {
                        status = "ok",
                        free_bytes = free_space
                    }
                else
                    health.checks.shared_dict = { status = "missing" }
                    health.status = "degraded"
                end
            end)
            if not ok then
                health.checks.shared_dict = { status = "error", error = err }
                health.status = "error"
            end

            -- Check LuaJIT version availability
            health.checks.luajit = {
                status = "ok",
                version = jit.version
            }

            local cjson = require "cjson"
            if health.status == "ok" then
                ngx.status = 200
            else
                ngx.status = 503
            end
            ngx.header["Content-Type"] = "application/json"
            ngx.say(cjson.encode(health))
        }
    }
}

Reload OpenResty:

openresty -s reload

Now add a Vigilmon monitor for this endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-openresty-host/health
3. Set Expected HTTP status to 200.
4. Set Expected response body contains to "status":"ok".
5. Click Save.

A 503 from this endpoint means the Lua runtime is healthy enough to respond but detected an internal problem (e.g. exhausted shared memory). A connection failure means OpenResty is down entirely.

Step 4: Monitor Nginx Worker Process Health via Stub Status

OpenResty includes the ngx_http_stub_status_module. Expose it on an internal path for connection count monitoring:

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    allow YOUR_MONITORING_IP;
    deny all;
    access_log off;
}

Reload OpenResty, then verify:

curl http://localhost/nginx_status
# Active connections: 42
# server accepts handled requests
#  1234567 1234567 9876543
# Reading: 0 Writing: 1 Waiting: 41

Add a Vigilmon monitor:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-openresty-host/nginx_status
3. Set Expected HTTP status to 200.
4. Set Expected response body contains to Active connections.
5. Click Save.

This confirms the stub status module is responding. For connection count alerting (detecting a spike that indicates a slow-loris attack or upstream failure causing connection pile-up), use Vigilmon's keyword alert: set Alert when response body contains to Active connections: 1 with a threshold your configuration can't sustain — though this requires Vigilmon's keyword alerting feature.

Step 5: Monitor Upstream Connection Pool Health

OpenResty API gateways proxy to upstream services. If an upstream pool exhausts or a backend goes down, OpenResty returns 502 Bad Gateway to clients.

Add a monitor that proxies through to a known-good upstream endpoint:

http://your-openresty-host/api/health

Where /api/health routes through OpenResty to a backend health endpoint. Set Expected HTTP status to 200.

This catches two failure modes at once: OpenResty upstream routing failure (502) and backend service failure (503). Combine it with a direct backend monitor:

http://your-backend-host:8080/health

If the direct backend monitor is green but the proxied OpenResty monitor is red, the problem is in OpenResty's upstream configuration or connection pool. If both are red, the backend is down.

For lua-resty-upstream-healthcheck, which manages upstream health in Lua, expose a status page:

location /upstream-status {
    access_log off;
    allow YOUR_MONITORING_IP;
    deny all;
    content_by_lua_block {
        local hc = require "resty.upstream.healthcheck"
        ngx.say(hc.status_page())
    }
}

Add a Vigilmon monitor on this endpoint with Expected response body contains set to healthy to confirm at least one upstream is in the healthy pool.

Step 6: Monitor the Rate Limiter and WAF

Rate limiting and WAF rule processing in OpenResty runs in the Lua request processing pipeline. A failing rate limiter returns unexpected status codes to legitimate users; a WAF misconfiguration can block all traffic.

Add a monitor using a known-safe request that should always pass WAF rules and not be rate limited:

https://your-openresty-host/health

The /health endpoint you created in Step 3 should always be exempt from rate limiting (add limit_req_zone bypass for /health in your Nginx config). If this endpoint starts returning 429 Too Many Requests or 403 Forbidden, your rate limiter or WAF has a configuration problem.

For LuaRocks package dependency health, add a check in your /health endpoint:

-- Inside the health content_by_lua_block
local ok_resty_redis, redis = pcall(require, "resty.redis")
health.checks.lua_modules = {
    resty_redis = ok_resty_redis and "ok" or "missing"
}

This surfaces missing or broken Lua module dependencies in the health endpoint response, which Vigilmon monitors.

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, PagerDuty, or email.
2. For HTTP monitors on port 80/443, set Consecutive failures before alert to 2 — Nginx worker recycling can cause a single probe to fail.
3. For SSL certificate monitors, set Consecutive failures before alert to 1 — a certificate problem needs immediate attention.
4. For the Lua health endpoint (/health), set Consecutive failures before alert to 2.
5. Use Maintenance windows during OpenResty configuration reloads:

# Open maintenance window
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 2}'

# Reload OpenResty config
openresty -s reload

# Maintenance window expires automatically

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP availability | :80 | Nginx process down, port not listening | | HTTPS availability + SSL | :443 | TLS failure, certificate expiry | | Lua health endpoint | /health | Lua runtime error, shared dict exhausted | | Nginx stub status | /nginx_status | Worker process failure | | Proxied upstream | /api/health | Upstream pool exhaustion, backend down | | Upstream healthcheck | /upstream-status | All uptime peers unhealthy |

OpenResty's layered architecture — Nginx workers, LuaJIT runtime, shared memory dicts, upstream pools — means failures are rarely all-or-nothing. Nginx might be up while the Lua rate limiter is blocking all requests; upstream pools might be exhausted while the stub status shows normal connection counts. With Vigilmon monitoring each layer independently, you get precise failure attribution rather than "something is wrong with the API gateway."