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_formatto 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 requestsnginx_http_request_duration_seconds- Request duration in secondsnginx_upstream_response_time_seconds- Upstream response timenginx_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_checkenables automatic server health checksintervalcontrols how often checks occurfailsandpassesdefine thresholds for marking servers up/downtimeoutsets 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: 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.