nginx/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

https://nginx.org exposes a handful of metrics via the https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status. NGINX Plus provides a richer set of metrics via the https://nginx.org/en/docs/http/ngx_http_api_module.html 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 https://prometheus.io/.

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 https://github.com/nginx/kubernetes-ingress/ 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 https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status at /stub_status on port 8080.
  • For NGINX Plus, expose the https://nginx.org/en/docs/http/ngx_http_api_module.html#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 https://docs.docker.com/engine/reference/run/ command.

• To export NGINX metrics, run:

  console
  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:

  console
  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:

  console
  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:

  console
  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:

  console
  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

console
usage: nginx-prometheus-exporter [<flags>]


Flags:
  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
      --[no-]web.systemd-socket  Use systemd socket activation listeners instead
                                 of port listeners (Linux only). ($SYSTEMD_SOCKET)
      --web.listen-address=:9113 ...
                                 Addresses on which to expose metrics and web interface. Repeatable for multiple addresses. ($LISTEN_ADDRESS)
      --web.config.file=""       Path to configuration file that can enable TLS or authentication. See: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md ($CONFIG_FILE)
      --web.telemetry-path="/metrics"
                                 Path under which to expose metrics. ($TELEMETRY_PATH)
      --[no-]nginx.plus          Start the exporter for NGINX Plus. By default, the exporter is started for NGINX. ($NGINX_PLUS)
      --nginx.scrape-uri=http://127.0.0.1:8080/stub_status ...
                                 A URI or unix domain socket path for scraping NGINX or NGINX Plus metrics. For NGINX, the stub_status page must be available through the URI. For NGINX Plus -- the API. Repeatable for multiple URIs. ($SCRAPE_URI)
      --[no-]nginx.ssl-verify    Perform SSL certificate verification. ($SSL_VERIFY)
      --nginx.ssl-ca-cert=""     Path to the PEM encoded CA certificate file used to validate the servers SSL certificate. ($SSL_CA_CERT)
      --nginx.ssl-client-cert=""
                                 Path to the PEM encoded client certificate file to use when connecting to the server. ($SSL_CLIENT_CERT)
      --nginx.ssl-client-key=""  Path to the PEM encoded client certificate key file to use when connecting to the server. ($SSL_CLIENT_KEY)
      --[no-]nginx.proxy-protocol
                                 Pass proxy protocol payload to nginx listeners. ($PROXY_PROTOCOL)
      --nginx.timeout=5s         A timeout for scraping metrics from NGINX or NGINX Plus. ($TIMEOUT)
      --prometheus.const-label=PROMETHEUS.CONST-LABEL ...
                                 Label that will be used in every metric. Format is label=value. It can be repeated multiple times. ($CONST_LABELS)
      --log.level=info           Only log messages with the given severity or above. One of: [debug, info, warn, error]
      --log.format=logfmt        Output format of log messages. One of: [logfmt, json]
      --[no-]version             Show application version.

Exported Metrics

Common metrics

Metrics for NGINX OSS

https://nginx.org/en/docs/http/ngx_http_stub_status_module.html

Metrics for NGINX Plus

https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_connections

https://nginx.org/en/docs/http/ngx_http_api_module.html#http_

https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_ssl_object

https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_server_zone

https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_server_zone

https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_upstream

Note: for the state metric, the string values are converted to float64 using the following rule: "up" -> 1.0, "draining" -> 2.0, "down" -> 3.0, "unavail" –> 4.0, "checking" –> 5.0, "unhealthy" -> 6.0.