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

| Key         | Description                                     | Default   |
| ----------- | ----------------------------------------------- | --------- |
| 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      |

## 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

A much more powerful and flexible metrics API is available with NGINX Plus. A path needs to be configured in NGINX Plus first.

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

```bash
$ 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:

```bash
$ 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:

```ini
[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:

```ini
[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:

```bash
$ 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: \[<https://github.com/nginxinc/nginx-prometheus-exporter/blob/master/README.md>].

### Common metrics:

| Name       | Type  | Description                                                                                      | Labels |
| ---------- | ----- | ------------------------------------------------------------------------------------------------ | ------ |
| `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:

#### [Stub status metrics](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html)

| Name                         | Type    | Description                                                         | Labels |
| ---------------------------- | ------- | ------------------------------------------------------------------- | ------ |
| `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:

#### [Connections](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_connections)

| Name                             | Type    | Description                        | Labels |
| -------------------------------- | ------- | ---------------------------------- | ------ |
| `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            | \[]    |

#### [HTTP](https://nginx.org/en/docs/http/ngx_http_api_module.html#http_)

| Name                              | Type    | Description           | Labels |
| --------------------------------- | ------- | --------------------- | ------ |
| `nginxplus_http_requests_total`   | Counter | Total http requests   | \[]    |
| `nginxplus_http_requests_current` | Gauge   | Current http requests | \[]    |

#### [SSL](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_ssl_object)

| Name                              | Type    | Description                         | Labels |
| --------------------------------- | ------- | ----------------------------------- | ------ |
| `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 | \[]    |

#### [HTTP Server Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_server_zone)

| Name                               | Type    | Description                                        | Labels                                                                                                 |
| ---------------------------------- | ------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `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`                                                                                          |

#### [Stream Server Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_server_zone)

| Name                                       | Type    | Description                                           | Labels                                                                                    |
| ------------------------------------------ | ------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `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`                                                                             |

#### [HTTP Upstreams](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_upstream)

> 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`.

| Name                                      | Type    | Description                                                                                                                                                     | Labels                                                                                                        |
| ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `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`                                                                                                    |

#### [Stream Upstreams](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_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`.

| Name                                               | Type    | Description                                                                                                                                                        | Labels                |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| `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`            |

#### [Location Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_location_zone)

| Name                                | Type    | Description                                   | Labels                                                                                                   |
| ----------------------------------- | ------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `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`                                                                                          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fluentbit.io/manual/2.1/pipeline/inputs/nginx.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.