nginx-prometheus-exporter

NGINX Prometheus Exporter

NGINX Prometheus exporter makes it possible to monitor NGINX or NGINX Plus using Prometheus.

Table of Contents

• Overview
• Getting Started
  • A Note about NGINX Ingress Controller
  • Prerequisites
  • Running the Exporter in a Docker Container
  • Running the Exporter Binary
• Usage
  • Command-line Arguments
• Exported Metrics
  • Common metrics
  • Metrics for NGINX OSS
    • Stub status metrics
  • Metrics for NGINX Plus
    • Connections
    • HTTP
    • SSL
    • HTTP Server Zones
    • Stream Server Zones
    • HTTP Upstreams
    • Stream Upstreams
    • Stream Zone Sync
    • Location Zones
    • Resolver
    • HTTP Requests Rate Limiting
    • HTTP Connections Limiting
    • Stream Connections Limiting
    • Cache
    • Worker
    • License
• Troubleshooting
• Releases
  • Docker images
  • Binaries
  • Homebrew
  • Scoop
  • Nix
• Building the Exporter
  • Building the Docker Image
  • Building the Binary
• Grafana Dashboard
• SBOM (Software Bill of Materials)
  • Binaries
  • Docker Image
• Provenance
• Contacts
• Contributing
• Support
• License

Overview

NGINX exposes a handful of metrics via the stub_status page. NGINX Plus provides a richer set of metrics via the API and the monitoring dashboard. NGINX Prometheus exporter fetches the metrics from a single NGINX or NGINX Plus, converts the metrics into appropriate Prometheus metrics types and finally exposes them via an HTTP server to be collected by Prometheus.

Getting Started

In this section, we show how to quickly run NGINX Prometheus Exporter for NGINX or NGINX Plus.

A Note about NGINX Ingress Controller

If you’d like to use the NGINX Prometheus Exporter with NGINX Ingress Controller for Kubernetes, see this doc for the installation instructions.

Prerequisites

We assume that you have already installed Prometheus and NGINX or NGINX Plus. Additionally, you need to:

• Expose the built-in metrics in NGINX/NGINX Plus:
  • For NGINX, expose the stub_status page at /stub_status on port 8080.
  • For NGINX Plus, expose the API at /api on port 8080.
• Configure Prometheus to scrape metrics from the server with the exporter. Note that the default scrape port of the exporter is 9113 and the default metrics path -- /metrics.

Running the Exporter in a Docker Container

To start the exporter we use the docker run command.

• To export NGINX metrics, run:

  docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.5.1 --nginx.scrape-uri=http://<nginx>:8080/stub_status
  

  where <nginx> is the IP address/DNS name, through which NGINX is available.

• To export NGINX Plus metrics, run:

  docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.5.1 --nginx.plus --nginx.scrape-uri=http://<nginx-plus>:8080/api
  

  where <nginx-plus> is the IP address/DNS name, through which NGINX Plus is available.

Running the Exporter Binary

• To export NGINX metrics, run:

  nginx-prometheus-exporter --nginx.scrape-uri=http://<nginx>:8080/stub_status
  

  where <nginx> is the IP address/DNS name, through which NGINX is available.

• To export NGINX Plus metrics:

  nginx-prometheus-exporter --nginx.plus --nginx.scrape-uri=http://<nginx-plus>:8080/api
  

  where <nginx-plus> is the IP address/DNS name, through which NGINX Plus is available.

• To scrape NGINX metrics with unix domain sockets, run:

  nginx-prometheus-exporter --nginx.scrape-uri=unix:<nginx>:/stub_status
  

  where <nginx> is the path to unix domain socket, through which NGINX stub status is available.

Note. The nginx-prometheus-exporter is not a daemon. To run the exporter as a system service (daemon), you can follow the example in examples/systemd. Alternatively, you can run the exporter in a Docker container.

Usage

Command-line Arguments

…

Exported Metrics

Common metrics

Name Type Description Labels nginx_exporter_build_info Gauge Shows the exporter build information. branch, goarch, goos, goversion, revision, tags and version promhttp_metric_handler_requests_total Counter Total number of scrapes by HTTP status code. code (the HTTP status code) promhttp_metric_handler_requests_in_flight Gauge Current number of scrapes being served. [] go_* Multiple Go runtime metrics. []

Metrics for NGINX OSS

Name Type Description Labels nginx_up Gauge Shows the status of the last metric scrape: 1 for a successful scrape and 0 for a failed one []

Stub status metrics

Name Type Description Labels nginx_connections_accepted Counter Accepted client connections. [] nginx_connections_active Gauge Active client connections. [] nginx_connections_handled Counter Handled client connections. [] nginx_connections_reading Gauge Connections where NGINX is reading the request header. [] nginx_connections_waiting Gauge Idle client connections. [] nginx_connections_writing Gauge Connections where NGINX is writing the response back to the client. [] nginx_http_requests_total Counter Total http requests. []

Metrics for NGINX Plus

Name Type Description Labels nginxplus_up Gauge Shows the status of the last metric scrape: 1 for a successful scrape and 0 for a failed one []

Connections

Name Type Description Labels nginxplus_connections_accepted Counter Accepted client connections [] nginxplus_connections_active Gauge Active client connections [] nginxplus_connections_dropped Counter Dropped client connections dropped [] nginxplus_connections_idle Gauge Idle client connections []

HTTP

Name Type Description Labels nginxplus_http_requests_total Counter Total http requests [] nginxplus_http_requests_current Gauge Current http requests []

SSL

Name Type Description Labels nginxplus_ssl_handshakes Counter Successful SSL handshakes [] nginxplus_ssl_handshakes_failed Counter Failed SSL handshakes [] nginxplus_ssl_session_reuses Counter Session reuses during SSL handshake []

HTTP Server Zones

Name Type Description Labels nginxplus_server_zone_processing Gauge Client requests that are currently being processed server_zone nginxplus_server_zone_requests Counter Total client requests server_zone nginxplus_server_zone_responses Counter Total responses sent to clients code (the response status code. The values are: 1xx, 2xx, 3xx, 4xx and 5xx), server_zone nginxplus_server_zone_responses_codes Counter Total responses sent to clients by code code (the response status code. The [possible values](htt