Skip to content

in_nginx: update NGINX exporter metrics documentation #2286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eschabell merged 1 commit into from
Dec 9, 2025
+47 −33
Merged

in_nginx: update NGINX exporter metrics documentation #2286

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 47 additions & 33 deletions pipeline/inputs/nginx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,32 @@

The _NGINX exporter metrics_ input plugin scrapes metrics from the NGINX stub status handler.

{% hint style="info" %}

Metrics collected with NGINX Exporter Metrics flow through a separate pipeline from logs, and current filters don't operate on top of metrics.

{% endhint %}

## Configuration parameters

The plugin supports the following configuration parameters:

| Key | Description | Default |
|:-------------|:--------------------------------------------------------------------------------------------------------|:------------|
| `Host` | Name of the target host or IP address. | `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](../../administration/multithreading.md#inputs). | `false` |
| Key | Description | Default |
|:------------------|:--------------------------------------------------------------------------------------------------------|:------------|
| `host` | Name of the target host or IP address. | `localhost` |
| `nginx_plus` | Turn on NGINX Plus mode. | `true` |
| `port` | Port of the target NGINX service to connect to. | `80` |
| `scrape_interval` | The interval to scrape metrics from the NGINX service. | `5s` |
| `status_url` | The URL of the stub status handler. | `/status` |
| `threaded` | Indicates whether to run this input in its own [thread](../../administration/multithreading.md#inputs). | `false` |

### TLS / SSL

The NGINX exporter metrics input plugin supports TLS/SSL. For more details about the properties available and general configuration, refer to [Transport Security](../../administration/transport-security.md).

## Get started

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

```text
server {
Expand All @@ -27,7 +38,7 @@ server {
root /usr/share/nginx/html;
index index.html index.htm;
}
// configure the stub status handler.
# Configure the stub status handler.
location /status {
stub_status;
}
Expand All @@ -44,12 +55,11 @@ server {
listen [::]:80;
server_name localhost;

# enable /api/ location with appropriate access control in order
# to make use of NGINX Plus API
#
# 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
# Configure to allow requests from the server running Fluent Bit.
allow 192.168.1.*;
deny all;
}
Expand All @@ -64,7 +74,7 @@ From the command line you can let Fluent Bit generate the checks with the follow
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 you need to turn on the
To gather metrics from the command line with the NGINX Plus REST API, turn on the
`nginx_plus` property:

```shell
Expand All @@ -82,10 +92,11 @@ In your main configuration file append the following:
pipeline:
inputs:
- name: nginx_metrics
nginx_plus: off
host: 127.0.0.1
port: 80
status_URL: /status
status_url: /status
nginx_plus: off
scrape_interval: 5s

outputs:
- name: stdout
Expand All @@ -97,15 +108,16 @@ pipeline:

```text
[INPUT]
Name nginx_metrics
Nginx_Plus off
Host 127.0.0.1
Port 80
Status_URL /status
Name nginx_metrics
Host 127.0.0.1
Port 80
Status_URL /status
Nginx_Plus off
Scrape_Interval 5s

[OUTPUT]
Name stdout
Match *
Name stdout
Match *
```

{% endtab %}
Expand All @@ -120,10 +132,11 @@ And for NGINX Plus API:
pipeline:
inputs:
- name: nginx_metrics
nginx_plus: on
host: 127.0.0.1
port: 80
status_URL: /api
status_url: /api
nginx_plus: on
scrape_interval: 5s

outputs:
- name: stdout
Expand All @@ -135,15 +148,16 @@ pipeline:

```text
[INPUT]
Name nginx_metrics
Nginx_Plus on
Host 127.0.0.1
Port 80
Status_URL /api
Name nginx_metrics
Host 127.0.0.1
Port 80
Status_URL /api
Nginx_Plus on
Scrape_Interval 5s

[OUTPUT]
Name stdout
Match *
Name stdout
Match *
```

{% endtab %}
Expand All @@ -157,7 +171,7 @@ You can test against the NGINX server running on localhost by invoking it direct
fluent-bit -i nginx_metrics -p host=127.0.0.1 -p nginx_plus=off -o stdout -p match=* -f 1
```

Which should return something like the following:
This returns output similar to the following:

```text
...
Expand Down