Monitor NGINX Metrics with OpenTelemetry and SigNoz

Overview

This guide shows how to collect NGINX server metrics with the OpenTelemetry (OTel) Collector and visualize them in SigNoz.

The OTel Collector's nginx receiver periodically scrapes NGINX's stub_status endpoint and converts the output into metrics such as request counts and connection states.

Prerequisites

• An NGINX instance with the ngx_http_stub_status_module module available (included in most NGINX builds).
• The OpenTelemetry Collector installed and exporting to SigNoz. If you have not set this up yet, follow the VM install guide.
• A SigNoz Cloud account, or a self-hosted SigNoz instance.

Step 1: Enable the NGINX stub_status endpoint

The stub_status module exposes real-time server health metrics like active connections, handled requests, and connection states. The receiver reads metrics from this endpoint.

Add a location block to your NGINX server configuration to expose the status page:

server {
    listen       80;
    server_name  localhost;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;   # restrict to the collector host
        deny all;
    }
}

The allow/deny directives restrict the status page to local access, which is enough when the Collector runs on the same host. Adjust the allowed address if the Collector runs elsewhere.

Reload NGINX and confirm the endpoint responds:

nginx -t && nginx -s reload
curl http://localhost:80/nginx_status

You should see output similar to:

Active connections: 2
server accepts handled requests
 12 12 12
Reading: 0 Writing: 1 Waiting: 1

Step 2: Configure the nginx receiver

Add the nginx receiver to your OTel Collector config, pointing endpoint at the status page from Step 1:

receivers:
  nginx:
    endpoint: "http://localhost:80/nginx_status"
    collection_interval: 10s
    initial_delay: 1s

Configuration parameters:

• endpoint (required): URL of the NGINX stub_status page. Upstream default is http://localhost:80/status.
• collection_interval (default: 10s): How often to scrape the endpoint.
• initial_delay (default: 1s): Delay before the first scrape after startup.

See the receiver README for advanced options such as timeout and TLS.

Step 3: Enable the receiver in the metrics pipeline

Add the nginx receiver to your metrics pipeline so the scraped metrics are exported to SigNoz:

service:
  pipelines:
    metrics:
      receivers: [otlp, nginx]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]

Use the same processors and exporter names that already exist in your Collector config. In the VM install guide, those entries are resourcedetection, batch, and otlphttp.

Restart the Collector to apply the changes.

Metrics collected

Validate

Once the Collector restarts, NGINX metrics start flowing to SigNoz.

1. Open the Metrics Explorer and search for nginx.requests. Live data points confirm the pipeline is working.
2. If a metric shows no movement, send some traffic to NGINX (for example curl http://localhost/ a few times) and re-check.

You can also import the pre-configured NGINX dashboard to monitor critical NGINX metrics.

Troubleshooting

1. No metrics appearing in SigNoz

• Verify the NGINX status endpoint is accessible from the Collector host (curl http://localhost:80/nginx_status).
• Check the Collector logs for connection or export errors.
• Ensure any firewall allows the Collector to reach the status endpoint.

2. Permission denied errors

• Check the allow/deny rules on the stub_status location.
• Verify the Collector's IP address is allowed.

3. Metrics showing zero values

• Confirm NGINX is receiving traffic.
• Verify the status endpoint shows non-zero values.
• Note that counters reset when NGINX restarts.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack.

If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.