Connect NGINX to Watchlog

This guide explains how to connect NGINX to Watchlog so you can monitor metrics such as request status codes, response times, and active connections.

Prerequisite: Watchlog Agent installed

Make sure the Watchlog Agent is already installed on your server. If it is not installed yet, follow the installation guide first and then return to this page.

Step 1 – Configure NGINX

Add the following configuration to your NGINX config to expose the status endpoint and enable Watchlog-specific access logs.

1. Enable the NGINX status endpoint (stub_status):

server {
    listen 127.0.0.1:8080; # Change IP/port if needed
    server_name localhost;

    location /nginx_status {
        stub_status on;
        # Optionally restrict access:
        # allow 127.0.0.1;
        # deny all;
    }
}

2. Add the Watchlog log format and use it for the access log:

log_format watchlogFormat '$remote_addr - $remote_user [$time_local] '
                          '"$request" "$scheme://$host$request_uri" $status $body_bytes_sent '
                          '"$http_referer" "$http_user_agent" '
                          '$request_time $upstream_response_time $pipe $ssl_protocol $ssl_cipher';

access_log /var/log/nginx/access.log watchlogFormat;

3. Test and reload NGINX:

sudo nginx -t
sudo systemctl reload nginx

Step 2 – Update Watchlog Agent integration config

Tell the Watchlog Agent to monitor NGINX by updating the integration.json file.

Ubuntu

Go to /opt/watchlog-agent, open the integration.json file and update your configuration:

cd /opt/watchlog-agent
sudo vim integration.json
# (Make your changes and save)

Add or update the NGINX section as follows:

{
  "monitor": true,
  "service": "nginx",
  "accessLog": "/var/log/nginx/access.log",
  "nginx_status_url": "http://localhost:8080/nginx_status"
}

Note: All integration configurations are stored in this file.

Step 3 – Reload the Watchlog Agent

After saving integration.json, reload the Watchlog Agent with PM2:

sudo pm2 reload watchlog-agent

Step 4 – Verify the integration in Watchlog

1. Log in to the Watchlog dashboard.
2. Go to the NGINX integration section.
3. Confirm that:
   • Metrics from /nginx_status (connections, requests, etc.) are visible.
   • Access logs from /var/log/nginx/access.log are being ingested and displayed.

If you do not see data after a few minutes:

• Check that NGINX is receiving traffic.
• Re-check the access_log path and watchlogFormat in your NGINX config.
• Ensure the nginx_status_url is reachable from the server running the Watchlog Agent.