Skip to main content

Monitoring and Status

1. Enabling Stub Status

Directive Values Description
stub_status on | off Enables or disables the stub status module. Default is off.

Example: Enabling Stub Status

server {
    listen 80;
    server_name example.com;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}
Note: The stub_status directive is part of the ngx_http_stub_status_module, which is compiled by default in most Nginx distributions.

2. Understanding Status Metrics

Metric Description Unit Collection Method
active_connections Number of active client connections connections ngx_http_stub_status_module
accepted_connections Total number of accepted client connections connections ngx_http_stub_status_module
handled_connections Total number of handled client connections connections ngx_http_stub_status_module
requests Total number of client requests requests ngx_http_stub_status_module
reading Number of connections where Nginx is reading the request connections ngx_http_stub_status_module
writing Number of connections where Nginx is writing the response connections ngx_http_stub_status_module
waiting Number of idle client connections connections ngx_http_stub_status_module

Example: Enabling stub_status

server {
    listen 80;
    server_name example.com;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}
Note: The stub_status directive is part of the ngx_http_stub_status_module, which must be compiled into Nginx or enabled via a module.

3. Using Access Logs for Monitoring

Directive Description Default Notes
access_log Defines the path to the access log file /var/log/nginx/access.log Can be specified multiple times for different log formats
log_format Defines a custom log format combined Can be reused across multiple access_log directives

Example: Custom Log Format

log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access_custom.log custom;

Example: Log Rotation with logrotate

/var/log/nginx/*.log {
    daily
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    create 644 nginx nginx
}
Note: Access logs can become very large. Consider using log rotation to manage disk space.

Key Points for Log Monitoring

  • Use log_format to customize log output for better monitoring
  • Regularly rotate logs to prevent disk space issues
  • Monitor for unusual traffic patterns or error codes

4. Parsing Nginx Logs

Field Description Example Value
remote_addr Client IP address 192.168.1.1
remote_user Authenticated user john_doe
time_local Local time of request 25/Jul/2024:12:00:00 +0000
request Full HTTP request line GET /index.html HTTP/1.1
status HTTP status code 200
body_bytes_sent Bytes sent in response body 1234
http_referer Referer header value https://example.com/page
http_user_agent User agent string Mozilla/5.0...

Example: Log Format Configuration

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
access_log /var/log/nginx/access.log main;

Example: Log Parsing with Python

import re
from datetime import datetime

log_line = '192.168.1.1 - john_doe [25/Jul/2024:12:00:00 +0000] "GET /index.html HTTP/1.1" 200 1234 "https://example.com/page" "Mozilla/5.0..."'

pattern = re.compile(
    r'(?P<remote_addr>\S+) - (?P<remote_user>\S+) \[(?P<time_local>[^\]]+)\] "(?P<request>[^"]+)" (?P<status>\d+) (?P<body_bytes_sent>\d+) "(?P<http_referer>[^"]+)" "(?P<http_user_agent>[^"]+)"'
)

match = pattern.match(log_line)
if match:
    parsed_log = match.groupdict()
    print(f"IP: {parsed_log['remote_addr']}")
    print(f"Status: {parsed_log['status']}")
    print(f"User Agent: {parsed_log['http_user_agent']}")
Note: The log_format directive allows customizing the log format to include or exclude specific fields based on monitoring needs.

5. Integrating with Prometheus

Directive Description Values Notes
prometheus Enables Prometheus metrics collection on | off Default: off
prometheus_port Port to expose Prometheus metrics integer Default: 9148
prometheus_path Path to expose metrics endpoint string Default: /metrics

Example: Basic Prometheus Integration

server {
    listen 80;
    location / {
        proxy_pass http://backend;
    }

    location /metrics {
        prometheus on;
        prometheus_port 9148;
        prometheus_path /metrics;
    }
}
Note: Ensure the nginx-module-vts module is installed for full Prometheus integration.

Key Metrics Exposed

  • nginx_http_requests_total - Total number of HTTP requests
  • nginx_http_request_duration_seconds - Request duration in seconds
  • nginx_upstream_response_time_seconds - Upstream response time
  • nginx_http_status_codes - Count of HTTP status codes

6. Integrating with Grafana Dashboards

Example: Nginx Exporter Configuration

scrape_configs:
  - job_name: 'nginx'
    static_configs:
      - targets: ['localhost:9113']
Configuration Description Default Value
nginx.config.path Path to Nginx config file /etc/nginx/nginx.conf
nginx.status.uri URI to Nginx status page /nginx_status
nginx.exporter.port Port for Nginx exporter 9113
Note: Ensure the stub_status module is enabled in Nginx to expose metrics.

Example: Grafana Dashboard JSON

{
  "dashboard": {
    "title": "Nginx Metrics",
    "panels": [
      {
        "type": "graph",
        "title": "Requests per Second"
      }
    ]
  }
}

Comparison: Nginx Exporter vs InfluxDB

  • Nginx Exporter: Exports metrics to Prometheus
  • InfluxDB: Time-series database for storing metrics

7. Using Third-party Status Modules

Module Description Installation Configuration
nginx-module-vts Virtual Host Traffic Status module for Nginx apt-get install nginx-module-vts load_module modules/ngx_http_vhost_traffic_status_module.so;
nginx-module-sts Stream Traffic Status module for Nginx apt-get install nginx-module-sts load_module modules/ngx_stream_vhost_traffic_status_module.so;

Example: Enabling Virtual Host Traffic Status

server {
    listen 80;
    server_name example.com;

    location /status {
        vhost_traffic_status_display;
        vhost_traffic_status_display_format html;
    }
}
Note: These modules provide detailed metrics and real-time traffic statistics for Nginx configurations.

8. Monitoring Upstream Health

Directive Description Default Notes
upstream Defines a group of servers None Used with server blocks to define backend services
server Defines a server in an upstream group None Can include health check parameters
health_check Enables health checks for upstream servers Off Available in Nginx Plus; community version requires third-party modules
health_check_interval Interval between health checks 5s Configurable in seconds
health_check_timeout Timeout for health check requests 1s Configurable in seconds
health_check_failures Number of failures before marking server as down 1 Configurable integer
health_check_passes Number of successes before marking server as up 1 Configurable integer

Example: Basic upstream health check configuration

upstream backend {
    server 192.168.1.10:8080;
    server 192.168.1.11:8080;
    server 192.168.1.12:8080;

    health_check;
}

server {
    listen 80;
    location / {
        proxy_pass http://backend;
    }
}

Example: Advanced upstream health check with custom parameters

upstream api_backend {
    server 10.0.0.1:8080 weight=3;
    server 10.0.0.2:8080 weight=2;
    server 10.0.0.3:8080 backup;

    health_check interval=10s fails=2 passes=1 timeout=5s;
}

server {
    listen 80;
    location /api {
        proxy_pass http://api_backend;
    }
}
Note: The health_check directive is only available in Nginx Plus. For the open-source version, you must use third-party modules like nginx-module-healthcheck.

Upstream Health Check Configuration Summary

  • health_check enables automatic server health checks
  • interval controls how often checks occur
  • fails and passes define thresholds for marking servers up/down
  • timeout sets the maximum time to wait for a response

9. Tracking Response Times

Directive Description Default Notes
log_format Defines custom log format including response time combined Used in conjunction with access_log
access_log Enables logging of requests with response times off Can specify custom format and path

Example: Configuring response time logging

log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_time';

access_log /var/log/nginx/access.log custom;
Note: The $request_time variable represents the time spent processing the request in seconds, including time spent waiting for a response from upstream servers.

Response Time Metrics

  • $request_time: Total time to process the request (seconds)
  • $upstream_response_time: Time spent waiting for upstream server response (seconds)
  • $msec: Time in seconds with milliseconds precision

10. Monitoring SSL Certificate Expiry

Property Value Description
ssl_certificate /path/to/cert.pem Path to the SSL certificate file
ssl_certificate_key /path/to/key.pem Path to the private key file
ssl_trusted_certificate /path/to/trusted.pem Path to the trusted certificate file (optional)

Example: Check Certificate Expiry via Command Line

openssl x509 -in /path/to/cert.pem -noout -dates

Example: Set Up a Cron Job to Monitor Certificates

0 0 * * * /usr/bin/openssl x509 -in /etc/nginx/ssl/cert.pem -noout -dates | grep "notAfter" >> /var/log/cert_expiry.log
Note: Ensure that the certificate file is readable by the Nginx process and that the expiration date is checked regularly to avoid service disruption.

11. Setting Up Alerts

Example: Basic Alert Configuration

server {
    listen 80;
    server_name example.com;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}
Directive Description Values Notes
stub_status Enables status page on | off Required for monitoring
access_log Controls access logging off Recommended for status pages
allow IP address access control 127.0.0.1 Restricts access to local host
Note: The status page is accessible only from the allowed IP address.

Example: Alert Threshold Configuration

# Example script to check status and send alert
#!/bin/bash
STATUS=$(curl -s http://localhost/nginx_status | grep Active | awk '{print $2}')
if [ "$STATUS" -gt 100 ]; then
    echo "High active connections: $STATUS"
    # Send alert via email or webhook
fi

12. Implementing Real-time Metrics

Example: Configuring Prometheus Exporter

server {
    listen 80;
    location /metrics {
        prometheus_exporter;
    }
}
Directive Description Values Notes
prometheus_exporter Enables Prometheus metrics export on, off Requires nginx-module-prometheus module
Note: Ensure the Prometheus exporter module is installed and enabled in your Nginx build.

Example: Using OpenTelemetry Collector

receivers:
  nginx:
    endpoint: "localhost:8080"
exporters:
  otlp:
    endpoint: "otel-collector:4317"

Real-time Metrics Overview

  • Prometheus exporter provides metrics in text/plain format
  • OpenTelemetry integration allows for advanced observability
  • Metrics include request count, response time, and status codes

Was this article helpful?