Export NGINX metrics in a format prometheus can understand

In the previous tutorial, we saw how to enable the stub_status module and expose it as an http endpoint. Prometheus server, however, cannot directly consume metrics exposed by NGINX at localhost/basic_status endpoint as-is. Prometheus consumes metrics from targets which are http endpoints serving metrics in plaintext format. We are going to use nginx-prometheus-exporter to export NGINX metrics to prometheus.

Install nginx-prometheus-exporter

Build nginx-prometheus-exporter from its source code by following their guide. On a debian based distribution, prerequisites can be installed using following sample instruction

# Install make
$ sudo apt install make

# Install git
$ sudo apt install git

Install golang by following these instructions. Assuming you downloaded go1.21.6.linux-amd64.tar.gz, following instructions should install the downloaded archive:

$  rm -rf /usr/local/go && tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz

# Add following line to your $HOME/.bashrc file
export PATH=$PATH:/usr/local/go/bin

Once you have prerequisites installed, build the binary by running make on downloaded nginx-prometheus-exporter source.

Verify the installation

Verify the installation by running nginx-prometheus-exporter as follows:

nginx-prometheus-exporter --nginx.scrape-uri=http://127.0.0.1:81/basic_status

With nginx-prometheus-exporter still running, run following command in a new terminal to ensure that metrics are being exported in prometheus format:

$ curl localhost:9113/metrics

Output should look something like following:

# HELP nginx_connections_accepted Accepted client connections
# TYPE nginx_connections_accepted counter
nginx_connections_accepted 287245223
# HELP nginx_connections_active Active client connections
# TYPE nginx_connections_active gauge
nginx_connections_active 2335
# HELP nginx_connections_handled Handled client connections
# TYPE nginx_connections_handled counter
nginx_connections_handled 287245223
# HELP nginx_connections_reading Connections where NGINX is reading the request header
# TYPE nginx_connections_reading gauge
nginx_connections_reading 91
# HELP nginx_connections_waiting Idle client connections
# TYPE nginx_connections_waiting gauge
nginx_connections_waiting 232
# HELP nginx_connections_writing Connections where NGINX is writing the response back to the client
# TYPE nginx_connections_writing gauge
nginx_connections_writing 153
# HELP nginx_http_requests_total Total http requests
# TYPE nginx_http_requests_total counter
nginx_http_requests_total 382246503
# HELP nginx_up Status of the last metric scrape
# TYPE nginx_up gauge
nginx_up 1
# HELP nginxexporter_build_info Exporter build information
# TYPE nginxexporter_build_info gauge
nginxexporter_build_info{arch="linux/amd64",commit="",date="",dirty="false",go="go1.20.1",version="0.11.0"} 1

Install nginx-prometheus-exporter as a service

We have run nginx-prometheus-exporter as a command, but it will die as soon as your ssh session terminates. In order to keep running nginx-prometheus-exporter even after the ssh session terminates, we need to run nginx-prometheus-exporter as a service. Copy following systemd config and paste it to /lib/systemd/system/nginx-prometheus-exporter.service file.

[Unit]
Description=A service that takes built-in metrics in NGINX/NGINX Plus, converts the metrics into appropriate Prometheus metrics types, and finally exposes them via an HTTP server to be collected by Prometheus
Documentation=https://github.com/nginxinc/nginx-prometheus-exporter
After=nginx.service
Requires=nginx.service


[Service]
Type=simple
WorkingDirectory=/home/ubuntu/work/nginx-prometheus-exporter-0.11.0
ExecStart=/home/ubuntu/work/nginx-prometheus-exporter-0.11.0/nginx-prometheus-exporter -nginx.scrape-uri=http://127.0.0.1:81/basic_status
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Update WorkingDirectory and ExecStart to use the appropriate path where you installed nginx-prometheus-exporter. Start nginx-prometheus-exporter as a service using following command:

$ sudo systemctl start nginx-prometheus-exporter.service

Now nginx-prometheus-exporter is running in the background. You can verify it by running curl localhost:9113/metrics. You should see NGINX metrics in prometheus format.

In order to ensure that nginx-prometheus-exporter service starts on reboot, enable it using the following command.

$ sudo systemctl enable nginx-prometheus-exporter
Created symlink /etc/systemd/system/multi-user.target.wants/nginx-prometheus-exporter.service → /lib/systemd/system/nginx-prometheus-exporter.service.
$

In the next tutorial, we will install prometheus server to import these metrics.

Have any feedback?

If you have any feedback regarding this article or need a tutorial on any specific topic, please submit this feedback form.