Monitor NGINX Metrics with OpenTelemetry and SigNoz

This guide shows you how to collect NGINX server metrics with the OpenTelemetry Collector and send them to SigNoz. The Collector's nginx receiver scrapes the NGINX stub_status page and turns it into request and connection metrics.

Prerequisites

NGINX with the stub_status module (included in the nginx.org packages and the official Docker image)
The OpenTelemetry Collector sending data to SigNoz (VM install guide)
An instance of SigNoz (either Cloud or Self-Hosted)

Send metrics to SigNoz

Step 1. Enable the stub_status endpoint

The stub_status module reports active connections, handled requests, and connection states on a status page. Add a location block for it to a server block in your NGINX configuration:

server {
    listen       80;
    server_name  localhost;
 
    location /nginx_status {
        stub_status;
        allow 127.0.0.1;   # the Collector host
        deny all;
    }
}

The allow and deny lines limit the page to requests from the same host. If the Collector runs on another host, replace 127.0.0.1 with its IP address.

Reload NGINX and check the page:

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

The output looks like this:

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

Step 2. Add the nginx receiver

Add the nginx receiver to /etc/otelcol-contrib/config.yaml, under the existing receivers section. Point endpoint at the status page from Step 1:

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

endpoint: URL of the stub_status page. The receiver default is http://localhost:80/status, so set it to match your location.
collection_interval: How often the receiver scrapes the page. The default is 10s.

See the receiver README for TLS and timeout options.

Step 3. Add the receiver to the metrics pipeline

Add nginx to the receivers list of the metrics pipeline. Keep the processors and exporters your config already has:

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

The processor and exporter names match the VM install guide config.

NGINX metrics carry no service.name. To add one, define a resource processor that upserts service.name (for example, nginx) and add it to the processors list of the metrics pipeline.

Step 4. Restart the Collector

sudo systemctl restart otelcol-contrib

If you run the Collector binary directly, stop it and start it again with the same --config flag.

Validate

Send a few requests to NGINX, for example curl http://localhost/.
Open SigNoz and navigate to Metrics > Explorer.
Search for nginx.requests. New data points appear every collection interval.
Query nginx.connections_current and group by state to see active, reading, writing, and waiting connections.

Metrics collected

Metric	Type	Unit	Description
`nginx.requests`	Sum (monotonic)	requests	Total requests since NGINX started.
`nginx.connections_accepted`	Sum (monotonic)	connections	Total accepted client connections.
`nginx.connections_handled`	Sum (monotonic)	connections	Total handled connections. Equals `nginx.connections_accepted` unless NGINX hits a resource limit such as `worker_connections`.
`nginx.connections_current`	Sum (non-monotonic)	connections	Current connections, split by the `state` attribute (`active`, `reading`, `writing`, `waiting`).

The counters reset when NGINX restarts.

Troubleshooting

Check the Collector logs first:

sudo journalctl -u otelcol-contrib -f

Why do the logs show `expected 200 response, got 403`?

The allow and deny rules on the stub_status location block the Collector. Add the Collector host's IP address with an allow line, then reload NGINX.

Why do the logs show `failed to parse response body`?

The receiver endpoint points at a page that is not the stub_status page. Set endpoint to the exact location from Step 1, such as http://localhost:80/nginx_status.

Why are no NGINX metrics in SigNoz while the logs show no errors?

The metrics pipeline does not list the nginx receiver. Add it to receivers as shown in Step 3, then restart the Collector.

For more help with missing data, see Debug missing traces, logs, and metrics in SigNoz.

Next steps

Import the NGINX dashboard to chart these metrics
Trace NGINX requests with the native OpenTelemetry module
Collect NGINX logs with the same Collector
Create metrics-based alerts on request rate or active connections

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.