Monitor NGINX with OpenTelemetry

Osuite monitors NGINX through the OpenTelemetry Collector’s nginx receiver, which scrapes the stub_status endpoint and exports connection and request metrics over OTLP. They share resource attributes with your services, so a request surge in APM lines up with the reverse proxy in front of it.

Note

The nginx receiver ships in the Collector contrib distribution. Use otelcol-contrib (or any build that includes it), not the core otelcol binary.

Setup

Prerequisites

• NGINX built with the ngx_http_stub_status_module (included in the standard packages).
• A stub_status endpoint the Collector can reach.

Add a status location to your NGINX configuration and reload:

server {
    listen 80;

    location /status {
        stub_status on;
        allow 127.0.0.1;
        deny all;
    }
}

Reload NGINX and confirm the endpoint responds:

nginx -s reload
curl http://localhost/status

Caution

When the Collector runs on a different host, container, or pod, widen the allow directive to the Collector’s source address or subnet — otherwise the scrape is denied.

Configure the Collector

1. Add the nginx receiver, the otlp/osuite exporter, and a metrics pipeline. Pick the tab that matches where your Collector runs — only the receiver endpoint changes.

   Bare host

   receivers:
     nginx:
       endpoint: http://localhost:80/status
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [nginx]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Docker

   receivers:
     nginx:
       endpoint: http://nginx:80/status
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [nginx]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Kubernetes

   receivers:
     nginx:
       endpoint: http://nginx.default.svc.cluster.local:80/status
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [nginx]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

2. Start the Collector. On Docker and Kubernetes, the Collector and NGINX must share a network so the endpoint resolves.

Validate

What you should see

Metrics named nginx.* appear in Dashboards → Explore metrics within a minute, tagged with the host or pod the Collector runs on.

Data collected

Metric	Description	Unit
nginx.requests	Total requests served since start	{requests}
nginx.connections_accepted	Accepted client connections	{connections}
nginx.connections_handled	Handled connections (equal to accepted unless limits apply)	{connections}
nginx.connections_current	Current connections by state (active, reading, writing, waiting)	{connections}

stub_status exposes a small, fixed set of counters. For richer per-request latency and status-code metrics, generate NGINX access logs and collect them as logs.

Dashboards and alerts

Once metrics arrive, build an NGINX dashboard in the dashboard builder from the series above. Alerts in Osuite are PromQL-based — see Alerts. Useful starting conditions: a request-rate drop to zero (nginx.requests), and a rising active-connection count (nginx.connections_current) that signals backpressure.

Troubleshooting

• 403 or connection refused on /status — confirm the stub_status location exists and its allow list covers the Collector’s source address.
• Wrong module — confirm nginx -V lists --with-http_stub_status_module.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.