NGINX Exporter Metrics

NGINX Exporter Metrics input plugin scrapes metrics from the NGINX stub status handler.

Configuration Parameters

The plugin supports the following configuration parameters:

KeyDescriptionDefault

Host

Name of the target host or IP address to check.

localhost

Port

Port of the target nginx service to connect to.

80

Status_URL

The URL of the Stub Status Handler.

/status

Nginx_Plus

Turn on NGINX plus mode.

true

Threaded

Indicates whether to run this input in its own thread.

false

Getting Started

NGINX must be configured with a location that invokes the stub status handler. Here is an example configuration with such a location:

server {
    listen       80;
    listen  [::]:80;
    server_name  localhost;
    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }
    // configure the stub status handler.
    location /status {
        stub_status;
    }
}

Configuration with NGINX Plus REST API

Another metrics API is available with NGINX Plus. You must first configure a path in NGINX Plus.

server {
	listen       80;
	listen  [::]:80;
	server_name  localhost;

	# enable /api/ location with appropriate access control in order
	# to make use of NGINX Plus API
	#
	location /api/ {
		api write=on;
		# configure to allow requests from the server running fluent-bit
		allow 192.168.1.*;
		deny all;
	}
}

Command Line

From the command line you can let Fluent Bit generate the checks with the following options:

$ fluent-bit -i nginx_metrics -p host=127.0.0.1 -p port=80 -p status_url=/status -p nginx_plus=off -o stdout

To gather metrics from the command line with the NGINX Plus REST API we need to turn on the nginx_plus property, like so:

$ fluent-bit -i nginx_metrics -p host=127.0.0.1 -p port=80 -p nginx_plus=on -p status_url=/api -o stdout

Configuration File

In your main configuration file append the following Input & Output sections:

[INPUT]
    Name          nginx_metrics
    Host          127.0.0.1
    Port          80
    Status_URL    /status
    Nginx_Plus    off

[OUTPUT]
    Name   stdout
    Match  *

And for NGINX Plus API:

[INPUT]
    Name          nginx_metrics
    Nginx_Plus    on
    Host          127.0.0.1
    Port          80
    Status_URL    /api

[OUTPUT]
    Name   stdout
    Match  *

Testing

You can quickly test against the NGINX server running on localhost by invoking it directly from the command line:

$ fluent-bit -i nginx_metrics -p host=127.0.0.1 -p nginx_plus=off -o stdout -p match=* -f 1
Fluent Bit v2.x.x
* Copyright (C) 2019-2020 The Fluent Bit Authors
* Copyright (C) 2015-2018 Treasure Data
* Fluent Bit is a CNCF sub-project under the umbrella of Fluentd
* https://fluentbit.io

2021-10-14T19:37:37.228691854Z nginx_connections_accepted = 788253884
2021-10-14T19:37:37.228691854Z nginx_connections_handled = 788253884
2021-10-14T19:37:37.228691854Z nginx_http_requests_total = 42045501
2021-10-14T19:37:37.228691854Z nginx_connections_active = 2009
2021-10-14T19:37:37.228691854Z nginx_connections_reading = 0
2021-10-14T19:37:37.228691854Z nginx_connections_writing = 1
2021-10-14T19:37:37.228691854Z nginx_connections_waiting = 2008
2021-10-14T19:37:35.229919621Z nginx_up = 1

Exported Metrics

This documentation is copied from the NGINX Prometheus Exporter metrics documentation on GitHub.

Common metrics:

NameTypeDescriptionLabels

nginx_up

Gauge

Shows the status of the last metric scrape: 1 for a successful scrape and 0 for a failed one

[]

Metrics for NGINX OSS:

NameTypeDescriptionLabels

nginx_connections_accepted

Counter

Accepted client connections.

[]

nginx_connections_active

Gauge

Active client connections.

[]

nginx_connections_handled

Counter

Handled client connections.

[]

nginx_connections_reading

Gauge

Connections where NGINX is reading the request header.

[]

nginx_connections_waiting

Gauge

Idle client connections.

[]

nginx_connections_writing

Gauge

Connections where NGINX is writing the response back to the client.

[]

nginx_http_requests_total

Counter

Total http requests.

[]

Metrics for NGINX Plus:

NameTypeDescriptionLabels

nginxplus_connections_accepted

Counter

Accepted client connections

[]

nginxplus_connections_active

Gauge

Active client connections

[]

nginxplus_connections_dropped

Counter

Dropped client connections dropped

[]

nginxplus_connections_idle

Gauge

Idle client connections

[]

NameTypeDescriptionLabels

nginxplus_http_requests_total

Counter

Total http requests

[]

nginxplus_http_requests_current

Gauge

Current http requests

[]

NameTypeDescriptionLabels

nginxplus_ssl_handshakes

Counter

Successful SSL handshakes

[]

nginxplus_ssl_handshakes_failed

Counter

Failed SSL handshakes

[]

nginxplus_ssl_session_reuses

Counter

Session reuses during SSL handshake

[]

NameTypeDescriptionLabels

nginxplus_server_zone_processing

Gauge

Client requests that are currently being processed

server_zone

nginxplus_server_zone_requests

Counter

Total client requests

server_zone

nginxplus_server_zone_responses

Counter

Total responses sent to clients

code (the response status code. The values are: 1xx, 2xx, 3xx, 4xx and 5xx), server_zone

nginxplus_server_zone_discarded

Counter

Requests completed without sending a response

server_zone

nginxplus_server_zone_received

Counter

Bytes received from clients

server_zone

nginxplus_server_zone_sent

Counter

Bytes sent to clients

server_zone

NameTypeDescriptionLabels

nginxplus_stream_server_zone_processing

Gauge

Client connections that are currently being processed

server_zone

nginxplus_stream_server_zone_connections

Counter

Total connections

server_zone

nginxplus_stream_server_zone_sessions

Counter

Total sessions completed

code (the response status code. The values are: 2xx, 4xx, and 5xx), server_zone

nginxplus_stream_server_zone_discarded

Counter

Connections completed without creating a session

server_zone

nginxplus_stream_server_zone_received

Counter

Bytes received from clients

server_zone

nginxplus_stream_server_zone_sent

Counter

Bytes sent to clients

server_zone

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_state

Gauge

Current state

server, upstream

nginxplus_upstream_server_active

Gauge

Active connections

server, upstream

nginxplus_upstream_server_limit

Gauge

Limit for connections which corresponds to the max_conns parameter of the upstream server. Zero value means there is no limit

server, upstream

nginxplus_upstream_server_requests

Counter

Total client requests

server, upstream

nginxplus_upstream_server_responses

Counter

Total responses sent to clients

code (the response status code. The values are: 1xx, 2xx, 3xx, 4xx and 5xx), server, upstream

nginxplus_upstream_server_sent

Counter

Bytes sent to this server

server, upstream

nginxplus_upstream_server_received

Counter

Bytes received to this server

server, upstream

nginxplus_upstream_server_fails

Counter

Number of unsuccessful attempts to communicate with the server

server, upstream

nginxplus_upstream_server_unavail

Counter

How many times the server became unavailable for client requests (state 'unavail') due to the number of unsuccessful attempts reaching the max_fails threshold

server, upstream

nginxplus_upstream_server_header_time

Gauge

Average time to get the response header from the server

server, upstream

nginxplus_upstream_server_response_time

Gauge

Average time to get the full response from the server

server, upstream

nginxplus_upstream_keepalives

Gauge

Idle keepalive connections

upstream

nginxplus_upstream_zombies

Gauge

Servers removed from the group but still processing active client requests

upstream

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

NameTypeDescriptionLabels

nginxplus_stream_upstream_server_state

Gauge

Current state

server, upstream

nginxplus_stream_upstream_server_active

Gauge

Active connections

server , upstream

nginxplus_stream_upstream_server_limit

Gauge

Limit for connections which corresponds to the max_conns parameter of the upstream server. Zero value means there is no limit

server , upstream

nginxplus_stream_upstream_server_connections

Counter

Total number of client connections forwarded to this server

server, upstream

nginxplus_stream_upstream_server_connect_time

Gauge

Average time to connect to the upstream server

server, upstream

nginxplus_stream_upstream_server_first_byte_time

Gauge

Average time to receive the first byte of data

server, upstream

nginxplus_stream_upstream_server_response_time

Gauge

Average time to receive the last byte of data

server, upstream

nginxplus_stream_upstream_server_sent

Counter

Bytes sent to this server

server, upstream

nginxplus_stream_upstream_server_received

Counter

Bytes received from this server

server, upstream

nginxplus_stream_upstream_server_fails

Counter

Number of unsuccessful attempts to communicate with the server

server, upstream

nginxplus_stream_upstream_server_unavail

Counter

How many times the server became unavailable for client connections (state 'unavail') due to the number of unsuccessful attempts reaching the max_fails threshold

server, upstream

nginxplus_stream_upstream_zombies

Gauge

Servers removed from the group but still processing active client connections

upstream

NameTypeDescriptionLabels

nginxplus_location_zone_requests

Counter

Total client requests

location_zone

nginxplus_location_zone_responses

Counter

Total responses sent to clients

code (the response status code. The values are: 1xx, 2xx, 3xx, 4xx and 5xx), location_zone

nginxplus_location_zone_discarded

Counter

Requests completed without sending a response

location_zone

nginxplus_location_zone_received

Counter

Bytes received from clients

location_zone

nginxplus_location_zone_sent

Counter

Bytes sent to clients

location_zone

Last updated