NGINX Prometheus exporter makes it possible to monitor NGINX or NGINX Plus using Prometheus.
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.
Note: Currently it is only supported to run NGINX Prometheus Exporter in a Docker container.
In this section, we show how to quickly run NGINX Prometheus Exporter in a container for NGINX or NGINX Plus.
If you’d like to use the NGINX Prometheus Exporter with NGINX Ingress Controller for Kubernetes, see this doc for the installation instructions.
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_statuson port8080. - For NGINX Plus, expose the API at
/apion port8080.
- For NGINX, expose the stub_status page at
- Install Docker on the server where you’re planning to run the exporter.
- Configure Prometheus to scrape metrics from the server with the exporter. Note that the default scrape port of the exporter is
9113and the default metrics path --/metrics.
To start the exporter we use the docker run command.
-
To export NGINX metrics, run:
$ docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.1.0 -nginx.scrape-uri http://<nginx>:8080/stub_statuswhere
<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:0.1.0 -nginx.plus -nginx.scrape-uri http://<nginx-plus>:8080/apiwhere
<nginx-plus>is the IP address/DNS name, through which NGINX Plus is available.
Usage of ./nginx-prometheus-exporter:
-nginx.plus
Start the exporter for NGINX Plus. By default, the exporter is started for NGINX. The default value can be overwritten by NGINX_PLUS environment variable.
-nginx.scrape-uri string
A URI for scraping NGINX or NGINX Plus metrics.
For NGINX, the stub_status page must be available through the URI. For NGINX Plus -- the API. The default value can be overwritten by SCRAPE_URI environment variable. (default "http://127.0.0.1:8080/stub_status")
-nginx.ssl-verify
Perform SSL certificate verification. The default value can be overwritten by SSL_VERIFY environment variable.
-web.listen-address string
An address to listen on for web interface and telemetry. The default value can be overwritten by LISTEN_ADDRESS environment variable. (default ":9113")
-web.telemetry-path string
A path under which to expose metrics. The default value can be overwritten by TELEMETRY_PATH environment variable. (default "/metrics")
-
For NGINX, all stub_status metrics are exported. Connect to the
/metricspage of the running exporter to see the complete list of metrics along with their descriptions. -
For NGINX Plus, the following metrics are exported:
- Connections.
- HTTP.
- SSL.
- HTTP Server Zones.
- HTTP Upsteams. Note: for the
statemetric, 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.
Connect to the
/metricspage of the running exporter to see the complete list of metrics along with their descriptions. Note: to see server zones related metrics you must configure status zones and to see upstream related metrics you must configure upstreams with a shared memory zone.
The exporter logs errors to the standard output. If the exporter doesn’t work as expected, check its logs using docker logs command.
For each release, we publish the corresponding Docker image at nginx/nginx-prometheus-exporter DockerHub repo. See the GitHub releases page for the list of all releases and the CHANGELOG.md for the changelog.
You can build the exporter image using the provided Makefile. Before building the image, make sure the following software is installed on your machine:
- make
- Docker
- git
To build the image, run:
$ make container
Note:
- golang is not required, as the exporter binary is built in a Docker container. See the Dockerfile.
- The Makefile supports a few variables which can override its default behaviour. See its content.
The commercial support is available for NGINX Plus customers when the NGINX Prometheus Exporter is used with NGINX Ingress Controller.