nginx/nginx-prometheus-exporter

https://github.com/nginx/nginx-prometheus-exporter/actions/workflows/ci.yml/badge.svg](https://github.com/nginx/nginx-prometheus-exporter/actions/workflows/ci.yml) https://app.fossa.com/api/projects/custom%2B5618%2Fgithub.com%2Fnginx%2Fnginx-prometheus-exporter.svg?type=shield](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginx%2Fnginx-prometheus-exporter?ref=badge_shield) https://goreportcard.com/badge/github.com/nginx/nginx-prometheus-exporter](https://goreportcard.com/report/github.com/nginx/nginx-prometheus-exporter)  !GitHub go.mod Go version !Docker Image Size (latest semver) ![Project Status: Active – The project has reached a stable, usable state and is being actively developed.]([]

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

  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

Stub status metrics

Metrics for NGINX Plus

Connections

HTTP

SSL

HTTP Server Zones

Stream Server Zones

HTTP Upstreams

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.