Prometheus exporter in Nginx - Step-by-Step Execution

Process Flow - Prometheus exporter

Start Nginx with Exporter Module

↓

Nginx collects metrics

↓

Exporter exposes metrics at /metrics

↓

Prometheus scrapes /metrics endpoint

↓

Prometheus stores and visualizes metrics

↓

End

Nginx runs with an exporter module that collects metrics and exposes them at a URL. Prometheus regularly fetches these metrics to monitor Nginx.

Execution Sample

Nginx

location /metrics {
    stub_status;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

Nginx configuration snippet exposing metrics at /metrics for Prometheus to scrape.

Process Table

Step	Action	Nginx State	Exporter Output	Prometheus Action
1	Nginx starts with /metrics location configured	Running with stub_status enabled	No metrics yet	No scrape yet
2	Nginx receives HTTP request at /metrics	Running	Generates current metrics snapshot	Receives metrics data
3	Prometheus scrapes /metrics endpoint	Running	Serves metrics text format	Stores metrics in time series database
4	Prometheus waits until next scrape interval	Running	Metrics updated continuously	Prepares for next scrape
5	Prometheus scrapes again	Running	New metrics snapshot served	Updates stored metrics
6	Monitoring dashboards update	Running	Metrics available	Visualizes Nginx performance
7	Nginx stops or exporter disabled	Stopped or no metrics	No metrics served	Scrape fails or stops

💡 Nginx stops or exporter disabled, so metrics are no longer served and Prometheus scraping ends.

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	Final
Nginx State	Starting	Running	Running	Running	Stopped or Running
Exporter Output	None	Metrics snapshot	Metrics served	Updated metrics	None or Metrics
Prometheus Action	Idle	Scraping	Storing metrics	Updating metrics	Stopped or Visualizing

Key Moments - 3 Insights

Why does Prometheus need the /metrics endpoint in Nginx?

Prometheus scrapes data by requesting /metrics. Without this endpoint, Prometheus cannot collect Nginx metrics. See execution_table step 2 and 3.

What happens if Nginx stops serving /metrics?

Prometheus scraping fails and monitoring stops. This is shown in execution_table step 7 where no metrics are served.

Why is access restricted to 127.0.0.1 in the config?

To secure metrics so only local Prometheus can access them, preventing unauthorized access. This is part of the configuration in execution_sample.

Visual Quiz - 3 Questions

Look at the execution_table, what is the Exporter Output at Step 3?

A Serves metrics text format

B No metrics yet

C Generates current metrics snapshot

D No metrics served

💡 Hint

Check the Exporter Output column at Step 3 in the execution_table.

At which step does Prometheus first store metrics data?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look at the Prometheus Action column in the execution_table for when storing starts.

If the allow 127.0.0.1; line is removed from the config, what changes in the execution?

A Prometheus cannot scrape metrics

B Metrics become accessible from any IP

C Nginx stops serving metrics

D Exporter output stops updating

💡 Hint

Refer to the variable_tracker and key_moments about access control in the config.

Concept Snapshot

Prometheus exporter in Nginx:
- Configure /metrics location with stub_status
- Restrict access (e.g., allow 127.0.0.1)
- Prometheus scrapes /metrics regularly
- Metrics served in text format
- Prometheus stores and visualizes metrics
- Exporter must run for monitoring to work

Full Transcript

This visual execution shows how Nginx acts as a Prometheus exporter by exposing metrics at the /metrics endpoint. Nginx starts with the stub_status module enabled and configured to serve metrics only to allowed IPs like 127.0.0.1. When Prometheus scrapes the /metrics URL, Nginx generates a current snapshot of metrics and serves them in a text format. Prometheus stores these metrics in its time series database and updates them on each scrape interval. If Nginx stops or the exporter is disabled, metrics are no longer served and Prometheus scraping fails. Access control in the configuration ensures only authorized clients can get metrics. This step-by-step trace helps beginners understand the flow from Nginx metrics exposure to Prometheus monitoring.

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