Introducing our new CEO Don Johnson - Read More

nginx/nginx-prometheus-exporter

Verified Publisher

By NGINX Inc.

Updated 2 days ago

NGINX Prometheus Exporter for NGINX and NGINX Plus

Image
Integration & Delivery
Monitoring & Observability
Web Servers
47

50M+

CIFOSSA StatusGo Report CardcodecovGitHub all releasesGitHub release (latest by SemVer)GitHub release (latest SemVer)nginx-prometheus-exporterGitHub go.mod Go versionDocker PullsDocker Image Size (latest semver)SlackProject 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

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.4.0 --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.4.0 --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
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)
      --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
NameTypeDescriptionLabels
nginx_exporter_build_infoGaugeShows the exporter build information.branch, goarch, goos, goversion, revision, tags and version
promhttp_metric_handler_requests_totalCounterTotal number of scrapes by HTTP status code.code (the HTTP status code)
promhttp_metric_handler_requests_in_flightGaugeCurrent number of scrapes being served.[]
go_*MultipleGo runtime metrics.[]
Metrics for NGINX OSS
NameTypeDescriptionLabels
nginx_upGaugeShows the status of the last metric scrape: 1 for a successful scrape and 0 for a failed one[]

Stub status metrics

NameTypeDescriptionLabels
nginx_connections_acceptedCounterAccepted client connections.[]
nginx_connections_activeGaugeActive client connections.[]
nginx_connections_handledCounterHandled client connections.[]
nginx_connections_readingGaugeConnections where NGINX is reading the request header.[]
nginx_connections_waitingGaugeIdle client connections.[]
nginx_connections_writingGaugeConnections where NGINX is writing the response back to the client.[]
nginx_http_requests_totalCounterTotal http requests.[]
Metrics for NGINX Plus
NameTypeDescriptionLabels
nginxplus_upGaugeShows the status of the last metric scrape: 1 for a successful scrape and 0 for a failed one[]

Connections

NameTypeDescriptionLabels
nginxplus_connections_acceptedCounterAccepted client connections[]
nginxplus_connections_activeGaugeActive client connections[]
nginxplus_connections_droppedCounterDropped client connections dropped[]
nginxplus_connections_idleGaugeIdle client connections[]

HTTP

NameTypeDescriptionLabels
nginxplus_http_requests_totalCounterTotal http requests[]
nginxplus_http_requests_currentGaugeCurrent http requests[]

SSL

NameTypeDescriptionLabels
nginxplus_ssl_handshakesCounterSuccessful SSL handshakes[]
nginxplus_ssl_handshakes_failedCounterFailed SSL handshakes[]
nginxplus_ssl_session_reusesCounterSession reuses during SSL handshake[]

HTTP Server Zones

NameTypeDescriptionLabels
nginxplus_server_zone_processingGaugeClient requests that are currently being processedserver_zone
nginxplus_server_zone_requestsCounterTotal client requestsserver_zone
nginxplus_server_zone_responsesCounterTotal responses sent to clientscode (the response status code. The values are: 1xx, 2xx, 3xx, 4xx and 5xx), server_zone
nginxplus_server_zone_responses_codesCounterTotal responses sent to clients by codecode (the response status code. The possible values are here), server_zone
nginxplus_server_zone_discardedCounterRequests completed without sending a responseserver_zone
nginxplus_server_zone_receivedCounterBytes received from clientsserver_zone
nginxplus_server_zone_sentCounterBytes sent to clientsserver_zone
nginxplus_server_ssl_handshakesCounterSuccessful SSL handshakesserver_zone
nginxplus_server_ssl_handshakes_failedCounterFailed SSL handshakesserver_zone
nginxplus_server_ssl_session_reusesCounterSession reuses during SSL handshakeserver_zone

Stream Server Zones

NameTypeDescriptionLabels
nginxplus_stream_server_zone_processingGaugeClient connections that are currently being processedserver_zone
nginxplus_stream_server_zone_connectionsCounterTotal connectionsserver_zone
nginxplus_stream_server_zone_sessionsCounterTotal sessions completedcode (the response status code. The values are: 2xx, 4xx, and 5xx), server_zone
nginxplus_stream_server_zone_discardedCounterConnections completed without creating a sessionserver_zone
nginxplus_stream_server_zone_receivedCounterBytes received from clientsserver_zone
nginxplus_stream_server_zone_sentCounterBytes sent to clientsserver_zone
nginxplus_stream_server_ssl_handshakesCounterSuccessful SSL handshakesserver_zone
nginxplus_stream_server_ssl_handshakes_failedCounterFailed SSL handshakesserver_zone
nginxplus_stream_server_ssl_session_reusesCounterSession reuses during SSL handshakeserver_zone

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.

NameTypeDescriptionLabels
nginxplus_upstream_server_stateGaugeCurrent stateserver, upstream
nginxplus_upstream_server_activeGaugeActive connectionsserver, upstream
nginxplus_upstream_server_limitGaugeLimit for connections which corresponds to the max_conns parameter of the upstream server. Zero value means there is no limitserver, upstream
nginxplus_upstream_server_requestsCounterTotal client requestsserver, upstream
nginxplus_upstream_server_responsesCounterTotal responses sent to clientscode (the response status code. The values are: 1xx, 2xx, 3xx, 4xx and 5xx), server, upstream
nginxplus_upstream_server_responses_codesCounterTotal responses sent to clients by codecode (the response status code. The possible values are here), server, upstream
nginxplus_upstream_server_sent`CounterBytes sent to this serverserver, upstream
nginxplus_upstream_server_receivedCounterBytes received to this serverserver, upstream
nginxplus_upstream_server_failsCounterNumber of unsuccessful attempts to communicate with the serverserver, upstream

Docker Pull Command

docker pull nginx/nginx-prometheus-exporter