Prometheus exporter in Nginx - Commands & Configuration

Introduction

When you want to monitor your Nginx web server's performance and health, you need a way to collect and expose metrics. A Prometheus exporter helps by gathering these metrics from Nginx and making them available for Prometheus to scrape and analyze.

When you want to track how many requests your Nginx server handles per second.

When you need to monitor the response status codes served by Nginx to detect errors.

When you want to see the current active connections to your Nginx server.

When you want to integrate Nginx metrics into a centralized monitoring system using Prometheus.

When you want to create alerts based on Nginx performance metrics.

Config File - nginx.conf

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    # Enable the stub_status module for basic metrics
    server {
        listen 8080;

        location /nginx_status {
            stub_status;
            allow 127.0.0.1;
            deny all;
        }
    }
}

This configuration enables the stub_status module on Nginx, which provides basic metrics like active connections and request counts at the /nginx_status URL. The server listens on port 8080 and only allows local access for security.

Commands

This command tests the Nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads Nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

This command fetches the Nginx metrics exposed by the stub_status module to verify it is working.

Terminal

curl http://127.0.0.1:8080/nginx_status

Expected Output

Active connections: 1 

server accepts handled requests

 10 10 20 

Reading: 0 Writing: 1 Waiting: 0

This command runs the official Nginx Prometheus exporter container, which scrapes the Nginx metrics from the stub_status URL and exposes them on port 9113 for Prometheus to collect.

Terminal

docker run -d --name nginx-prometheus-exporter -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.scrape-uri http://host.docker.internal:8080/nginx_status

Expected Output

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

→

-d - Run container in background

→

-p 9113:9113 - Map container port 9113 to host port 9113

→

-nginx.scrape-uri - Set the URL to scrape Nginx metrics from

This command fetches the metrics exposed by the Nginx Prometheus exporter to verify it is running and providing data.

Terminal

curl http://localhost:9113/metrics

Expected Output

# HELP nginx_connections_active Current active connections

# TYPE nginx_connections_active gauge

nginx_connections_active 1

# HELP nginx_http_requests_total Total HTTP requests

# TYPE nginx_http_requests_total counter

nginx_http_requests_total 20

Key Concept

If you remember nothing else from this pattern, remember: the Nginx stub_status module provides basic metrics that the Prometheus exporter scrapes and exposes for monitoring.

Common Mistakes

Not enabling the stub_status location in the Nginx config.

Without stub_status enabled, the exporter has no metrics to scrape and will show no data.

Add the stub_status location block in the Nginx config and reload Nginx.

Trying to access the stub_status URL from outside without allowing the IP.

Nginx denies access by default, so the exporter cannot scrape metrics.

Allow the exporter IP or localhost in the stub_status location with allow directives.

Not mapping the correct Nginx status URL in the exporter command.

The exporter won't find metrics if the scrape URI is incorrect.

Use the exact URL where stub_status is exposed, e.g., http://host.docker.internal:8080/nginx_status.

Summary

Configure Nginx to expose basic metrics using the stub_status module on a local URL.

Test and reload Nginx to apply the configuration safely.

Run the Nginx Prometheus exporter container to scrape and expose these metrics for Prometheus.

Verify the exporter is working by fetching metrics from its exposed endpoint.