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.

Practice

1. What is the main purpose of the stub_status module in nginx when used with Prometheus?

easy

A. To expose basic nginx metrics like active connections and requests

B. To serve static web pages faster

C. To block unauthorized IP addresses

D. To cache dynamic content for faster delivery

Solution

1. Step 1: Understand stub_status role

   The stub_status module provides a simple status page with metrics like active connections, accepts, handled, and requests.

2. Step 2: Connect stub_status to Prometheus

   Prometheus scrapes these metrics from the URL where stub_status is enabled to monitor nginx performance.

3. Final Answer:

   To expose basic nginx metrics like active connections and requests -> Option A

4. Quick Check:

   stub_status exposes metrics = C [OK]

Hint: stub_status shows nginx metrics, not content or blocking [OK]

Common Mistakes:

• Thinking stub_status caches content
• Confusing stub_status with IP blocking
• Assuming stub_status serves web pages

2. Which nginx configuration snippet correctly enables stub_status at the URL /metrics and restricts access to 127.0.0.1?

easy

A. location /metrics { stub_status on; allow all; }

B. location /metrics { stub_status; }

C. location /metrics { stub_status; allow 127.0.0.1; deny all; }

D. location /metrics { stub_status on; }

Solution

1. Step 1: Check stub_status syntax

   The correct directive is stub_status; without 'on'. It must be inside a location block.

2. Step 2: Verify access control

   To protect metrics, use allow 127.0.0.1; and deny all; inside the location.

3. Final Answer:

   location /metrics { stub_status; allow 127.0.0.1; deny all; } -> Option C

4. Quick Check:

   stub_status syntax + IP allow/deny = A [OK]

Hint: stub_status has no 'on'; protect with allow/deny [OK]

Common Mistakes:

• Using 'stub_status on;' which is invalid
• Not adding IP allow/deny rules
• Missing semicolon after stub_status

3. Given this nginx stub_status output scraped by Prometheus:

Active connections: 5
server accepts handled requests
 100 100 200
Reading: 1 Writing: 2 Waiting: 2

What is the value of 'Active connections' metric?

medium

A. 1

B. 100

C. 200

D. 5

Solution

1. Step 1: Identify Active connections line

   The first line shows 'Active connections: 5', so the active connections count is 5.

2. Step 2: Differentiate other numbers

   Numbers 100 and 200 relate to accepts, handled, and requests, not active connections.

3. Final Answer:

   5 -> Option D

4. Quick Check:

   Active connections = 5 [OK]

Hint: Active connections is the first number after label [OK]

Common Mistakes:

• Confusing accepts or requests with active connections
• Picking the largest number instead of the labeled one
• Ignoring the label and choosing Reading/Writing values

4. You configured nginx with stub_status at /metrics but Prometheus shows 'connection refused'. What is the most likely cause?

medium

A. nginx is not running or listening on the expected port

B. The stub_status directive is misspelled as stubstatus

C. Prometheus URL is missing the trailing slash

D. The location /metrics block is missing a root directive

Solution

1. Step 1: Understand 'connection refused' meaning

   This error means Prometheus cannot connect to nginx, likely because nginx is down or not listening on the port.

2. Step 2: Check other options

   Misspelling stub_status causes config errors but not connection refused. Missing slash or root directive won't cause connection refused.

3. Final Answer:

   nginx is not running or listening on the expected port -> Option A

4. Quick Check:

   Connection refused = nginx down or port closed [OK]

Hint: Connection refused means no server listening on port [OK]

Common Mistakes:

• Assuming URL slash causes connection refused
• Thinking config typos cause connection refused
• Believing root directive is required for stub_status

5. You want to expose nginx metrics at /metrics only to Prometheus server IP 10.0.0.5. Which configuration snippet correctly achieves this?

hard

A. location /metrics { stub_status on; allow 10.0.0.5; deny all; }

B. location /metrics { stub_status; allow 10.0.0.5; deny all; }

C. location /metrics { stub_status; allow all; deny 10.0.0.5; }

D. location /metrics { stub_status; deny all; allow 10.0.0.5; }

Solution

1. Step 1: Use correct stub_status syntax

   The directive is stub_status; without 'on'. It must be inside the location block.

2. Step 2: Apply IP allow/deny rules correctly

   To allow only 10.0.0.5, use allow 10.0.0.5; then deny all;. Order matters: allow first, then deny.

3. Final Answer:

   location /metrics { stub_status; allow 10.0.0.5; deny all; } -> Option B

4. Quick Check:

   Correct stub_status + allow IP then deny all = B [OK]

Hint: Allow IP first, then deny all; stub_status has no 'on' [OK]

Common Mistakes:

• Using 'stub_status on;' which is invalid
• Reversing allow and deny order
• Allowing all and denying the IP instead