1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
|
<!-- markdownlint-disable-next-line first-line-h1 -->
[](https://scorecard.dev/viewer/?uri=github.com/nginx/nginx-prometheus-exporter)
[](https://github.com/nginx/nginx-prometheus-exporter/actions/workflows/ci.yml)
[](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginx%2Fnginx-prometheus-exporter?ref=badge_shield)
[](https://goreportcard.com/report/github.com/nginx/nginx-prometheus-exporter)
[](https://codecov.io/gh/nginx/nginx-prometheus-exporter)
[](https://github.com/nginx/nginx-prometheus-exporter/releases/latest)
[](https://snapcraft.io/nginx-prometheus-exporter)
[](https://hub.docker.com/r/nginx/nginx-prometheus-exporter)
[](https://www.repostatus.org/#active)
# NGINX Prometheus Exporter
NGINX Prometheus exporter makes it possible to monitor NGINX or NGINX Plus using Prometheus.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents
- [Overview](#overview)
- [Getting Started](#getting-started)
- [A Note about NGINX Ingress Controller](#a-note-about-nginx-ingress-controller)
- [Prerequisites](#prerequisites)
- [Running the Exporter in a Docker Container](#running-the-exporter-in-a-docker-container)
- [Running the Exporter Binary](#running-the-exporter-binary)
- [Usage](#usage)
- [Command-line Arguments](#command-line-arguments)
- [Exported Metrics](#exported-metrics)
- [Common metrics](#common-metrics)
- [Metrics for NGINX OSS](#metrics-for-nginx-oss)
- [Stub status metrics](#stub-status-metrics)
- [Metrics for NGINX Plus](#metrics-for-nginx-plus)
- [Connections](#connections)
- [HTTP](#http)
- [SSL](#ssl)
- [HTTP Server Zones](#http-server-zones)
- [Stream Server Zones](#stream-server-zones)
- [HTTP Upstreams](#http-upstreams)
- [Stream Upstreams](#stream-upstreams)
- [Stream Zone Sync](#stream-zone-sync)
- [Location Zones](#location-zones)
- [Resolver](#resolver)
- [HTTP Requests Rate Limiting](#http-requests-rate-limiting)
- [HTTP Connections Limiting](#http-connections-limiting)
- [Stream Connections Limiting](#stream-connections-limiting)
- [Cache](#cache)
- [Worker](#worker)
- [Troubleshooting](#troubleshooting)
- [Releases](#releases)
- [Docker images](#docker-images)
- [Binaries](#binaries)
- [Homebrew](#homebrew)
- [Snap](#snap)
- [Scoop](#scoop)
- [Nix](#nix)
- [Building the Exporter](#building-the-exporter)
- [Building the Docker Image](#building-the-docker-image)
- [Building the Binary](#building-the-binary)
- [Grafana Dashboard](#grafana-dashboard)
- [SBOM (Software Bill of Materials)](#sbom-software-bill-of-materials)
- [Binaries](#binaries-1)
- [Docker Image](#docker-image)
- [Provenance](#provenance)
- [Contacts](#contacts)
- [Contributing](#contributing)
- [Support](#support)
- [License](#license)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Overview
[NGINX](https://nginx.org) exposes a handful of metrics via the [stub_status
page](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status). [NGINX
Plus](https://www.nginx.com/products/nginx/) provides a richer set of metrics via the
[API](https://nginx.org/en/docs/http/ngx_http_api_module.html) and the [monitoring
dashboard](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/). 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](https://prometheus.io/).
## 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](https://github.com/nginx/kubernetes-ingress/) for Kubernetes, see [this
doc](https://docs.nginx.com/nginx-ingress-controller/logging-and-monitoring/prometheus/) 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](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status) at `/stub_status` on port `8080`.
- For NGINX Plus, expose the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html#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](https://docs.docker.com/engine/reference/run/) command.
- To export NGINX metrics, run:
```console
docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.4.2 --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:
```console
docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.4.2 --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:
```console
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:
```console
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:
```console
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](./examples/systemd/README.md). Alternatively, you can run the exporter
in a Docker container.
## Usage
### Command-line Arguments
```console
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
| Name | Type | Description | Labels |
| -------------------------------------------- | -------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `nginx_exporter_build_info` | Gauge | Shows the exporter build information. | `branch`, `goarch`, `goos`, `goversion`, `revision`, `tags` and `version` |
| `promhttp_metric_handler_requests_total` | Counter | Total number of scrapes by HTTP status code. | `code` (the HTTP status code) |
| `promhttp_metric_handler_requests_in_flight` | Gauge | Current number of scrapes being served. | [] |
| `go_*` | Multiple | Go runtime metrics. | [] |
### Metrics for NGINX OSS
| 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 | [] |
#### [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
| Name | Type | Description | Labels |
| -------------- | ----- | ------------------------------------------------------------------------------------------------ | ------ |
| `nginxplus_up` | Gauge | Shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one | [] |
#### [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_responses_codes` | Counter | Total responses sent to clients by code | `code` (the response status code. The possible values are [here](https://www.nginx.com/resources/wiki/extending/api/http/)), `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` |
| `nginxplus_server_ssl_handshakes` | Counter | Successful SSL handshakes | `server_zone` |
| `nginxplus_server_ssl_handshakes_failed` | Counter | Failed SSL handshakes | `server_zone` |
| `nginxplus_server_ssl_session_reuses` | Counter | Session reuses during SSL handshake | `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` |
| `nginxplus_stream_server_ssl_handshakes` | Counter | Successful SSL handshakes | `server_zone` |
| `nginxplus_stream_server_ssl_handshakes_failed` | Counter | Failed SSL handshakes | `server_zone` |
| `nginxplus_stream_server_ssl_session_reuses` | Counter | Session reuses during SSL handshake | `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_responses_codes` | Counter | Total responses sent to clients by code | `code` (the response status code. The possible values are [here](https://www.nginx.com/resources/wiki/extending/api/http/)), `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_server_health_checks_checks` | Counter | Total health check requests | `server`, `upstream` |
| `nginxplus_upstream_server_health_checks_fails` | Counter | Failed health checks | `server`, `upstream` |
| `nginxplus_upstream_server_health_checks_unhealthy` | Counter | How many times the server became unhealthy (state 'unhealthy') | `server`, `upstream` |
| `nginxplus_upstream_server_ssl_handshakes` | Counter | Successful SSL handshakes | `server`, `upstream` |
| `nginxplus_upstream_server_ssl_handshakes_failed` | Counter | Failed SSL handshakes | `server`, `upstream` |
| `nginxplus_upstream_server_ssl_session_reuses` | Counter | Session reuses during SSL handshake | `server`, `upstream` |
| `nginxplus_upstream_keepalive` | 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_server_health_checks_checks` | Counter | Total health check requests | `server`, `upstream` |
| `nginxplus_stream_upstream_server_health_checks_fails` | Counter | Failed health checks | `server`, `upstream` |
| `nginxplus_stream_upstream_server_health_checks_unhealthy` | Counter | How many times the server became unhealthy (state 'unhealthy') | `server`, `upstream` |
| `nginxplus_stream_upstream_server_ssl_handshakes` | Counter | Successful SSL handshakes | `server`, `upstream` |
| `nginxplus_stream_upstream_server_ssl_handshakes_failed` | Counter | Failed SSL handshakes | `server`, `upstream` |
| `nginxplus_stream_upstream_server_ssl_session_reuses` | Counter | Session reuses during SSL handshake | `server`, `upstream` |
| `nginxplus_stream_upstream_zombies` | Gauge | Servers removed from the group but still processing active client connections | `upstream` |
#### [Stream Zone Sync](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_zone_sync)
| Name | Type | Description | Labels |
| ------------------------------------------------- | ------- | ------------------------------------------------------------ | ------ |
| `nginxplus_stream_zone_sync_zone_records_pending` | Gauge | The number of records that need to be sent to the cluster | `zone` |
| `nginxplus_stream_zone_sync_zone_records_total` | Gauge | The total number of records stored in the shared memory zone | `zone` |
| `nginxplus_stream_zone_sync_zone_bytes_in` | Counter | Bytes received by this node | [] |
| `nginxplus_stream_zone_sync_zone_bytes_out` | Counter | Bytes sent by this node | [] |
| `nginxplus_stream_zone_sync_zone_msgs_in` | Counter | Total messages received by this node | [] |
| `nginxplus_stream_zone_sync_zone_msgs_out` | Counter | Total messages sent by this node | [] |
| `nginxplus_stream_zone_sync_zone_nodes_online` | Gauge | Number of peers this node is connected to | [] |
#### [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_responses_codes` | Counter | Total responses sent to clients by code | `code` (the response status code. The possible values are [here](https://www.nginx.com/resources/wiki/extending/api/http/)), `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` |
#### [Resolver](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_resolver_zone)
| Name | Type | Description | Labels |
| ----------------------------- | ------- | ---------------------------------------------- | ---------- |
| `nginxplus_resolver_name` | Counter | Total requests to resolve names to addresses | `resolver` |
| `nginxplus_resolver_srv` | Counter | Total requests to resolve SRV records | `resolver` |
| `nginxplus_resolver_addr` | Counter | Total requests to resolve addresses to names | `resolver` |
| `nginxplus_resolver_noerror` | Counter | Total number of successful responses | `resolver` |
| `nginxplus_resolver_formerr` | Counter | Total number of FORMERR responses | `resolver` |
| `nginxplus_resolver_servfail` | Counter | Total number of SERVFAIL responses | `resolver` |
| `nginxplus_resolver_nxdomain` | Counter | Total number of NXDOMAIN responses | `resolver` |
| `nginxplus_resolver_notimp` | Counter | Total number of NOTIMP responses | `resolver` |
| `nginxplus_resolver_refused` | Counter | Total number of REFUSED responses | `resolver` |
| `nginxplus_resolver_timedout` | Counter | Total number of timed out request | `resolver` |
| `nginxplus_resolver_unknown` | Counter | Total requests completed with an unknown error | `resolver` |
#### [HTTP Requests Rate Limiting](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_limit_req_zone)
| Name | Type | Description | Labels |
| ------------------------------------------ | ------- | --------------------------------------------------------------------------- | ------ |
| `nginxplus_limit_request_passed` | Counter | Total number of requests that were neither limited nor accounted as limited | `zone` |
| `nginxplus_limit_request_rejected` | Counter | Total number of requests that were rejected | `zone` |
| `nginxplus_limit_request_delayed` | Counter | Total number of requests that were delayed | `zone` |
| `nginxplus_limit_request_rejected_dry_run` | Counter | Total number of requests accounted as rejected in the dry run mode | `zone` |
| `nginxplus_limit_request_delayed_dry_run` | Counter | Total number of requests accounted as delayed in the dry run mode | `zone` |
#### [HTTP Connections Limiting](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_limit_conn_zone)
| Name | Type | Description | Labels |
| --------------------------------------------- | ------- | ------------------------------------------------------------------------------ | ------ |
| `nginxplus_limit_connection_passed` | Counter | Total number of connections that were neither limited nor accounted as limited | `zone` |
| `nginxplus_limit_connection_rejected` | Counter | Total number of connections that were rejected | `zone` |
| `nginxplus_limit_connection_rejected_dry_run` | Counter | Total number of connections accounted as rejected in the dry run mode | `zone` |
#### [Stream Connections Limiting](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_limit_conn_zone)
| Name | Type | Description | Labels |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------ | ------ |
| `nginxplus_stream_limit_connection_passed` | Counter | Total number of connections that were neither limited nor accounted as limited | `zone` |
| `nginxplus_stream_limit_connection_rejected` | Counter | Total number of connections that were rejected | `zone` |
| `nginxplus_stream_limit_connection_rejected_dry_run` | Counter | Total number of connections accounted as rejected in the dry run mode | `zone` |
#### [Cache](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_cache)
| Name | Type | Description | Labels |
| ------------------------------------------- | ------- | ----------------------------------------------------------------------- | ------- |
| `nginxplus_cache_size` | Gauge | Total size of the cache | `cache` |
| `nginxplus_cache_max_size` | Gauge | Maximum size of the cache | `cache` |
| `nginxplus_cache_cold` | Gauge | Is the cache considered cold | `cache` |
| `nginxplus_cache_hit_responses` | Counter | Total number of cache hits | `cache` |
| `nginxplus_cache_hit_bytes` | Counter | Total number of bytes returned from cache hits | `cache` |
| `nginxplus_cache_stale_responses` | Counter | Total number of stale cache hits | `cache` |
| `nginxplus_cache_stale_bytes` | Counter | Total number of bytes returned from stale cache hits | `cache` |
| `nginxplus_cache_updating_responses` | Counter | Total number of cache hits while cache is updating | `cache` |
| `nginxplus_cache_updating_bytes` | Counter | Total number of bytes returned from cache while cache is updating | `cache` |
| `nginxplus_cache_revalidated_responses` | Counter | Total number of cache revalidations | `cache` |
| `nginxplus_cache_revalidated_bytes` | Counter | Total number of bytes returned from cache revalidations | `cache` |
| `nginxplus_cache_miss_responses` | Counter | Total number of cache misses | `cache` |
| `nginxplus_cache_miss_bytes` | Counter | Total number of bytes returned from cache misses | `cache` |
| `nginxplus_cache_expired_responses` | Counter | Total number of cache hits with expired TTL | `cache` |
| `nginxplus_cache_expired_bytes` | Counter | Total number of bytes returned from cache hits with expired TTL | `cache` |
| `nginxplus_cache_expired_responses_written` | Counter | Total number of cache hits with expired TTL written to cache | `cache` |
| `nginxplus_cache_expired_bytes_written` | Counter | Total number of bytes written to cache from cache hits with expired TTL | `cache` |
| `nginxplus_cache_bypass_responses` | Counter | Total number of cache bypasses | `cache` |
| `nginxplus_cache_bypass_bytes` | Counter | Total number of bytes returned from cache bypasses | `cache` |
| `nginxplus_cache_bypass_responses_written` | Counter | Total number of cache bypasses written to cache | `cache` |
| `nginxplus_cache_bypass_bytes_written` | Counter | Total number of bytes written to cache from cache bypasses | `cache` |
#### [Worker](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_worker)
| Name | Type | Description | Labels |
| ---------------------------------------- | ------- | ------------------------------------------------------------------------ | ----------- |
| `nginxplus_worker_connection_accepted` | Counter | The total number of accepted client connections | `id`, `pid` |
| `nginxplus_worker_connection_dropped` | Counter | The total number of dropped client connections | `id`, `pid` |
| `nginxplus_worker_connection_active` | Gauge | The current number of active client connections | `id`, `pid` |
| `nginxplus_worker_connection_idle` | Gauge | The current number of idle client connection | `id`, `pid` |
| `nginxplus_worker_http_requests_total` | Counter | The total number of client requests received | `id`, `pid` |
| `nginxplus_worker_http_requests_current` | Gauge | The current number of client requests that are currently being processed | `id`, `pid` |
Connect to the `/metrics` page of the running exporter to see the complete list of metrics along with their
descriptions. Note: to see server zones related metrics you must configure [status
zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone) and to see upstream related metrics you
must configure upstreams with a [shared memory zone](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone).
## Troubleshooting
The exporter logs errors to the standard output. When using Docker, if the exporter doesn’t work as expected, check its
logs using [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) command.
## Releases
### Docker images
We publish the Docker image on [DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter/),
[GitHub Container](https://github.com/nginx/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter),
[Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and
[Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter).
As an alternative, you can choose the _edge_ version built from the [latest commit](https://github.com/nginx/nginx-prometheus-exporter/commits/main)
from the main branch. The edge version is useful for experimenting with new features that are not yet published in a
stable release.
### Binaries
We publish the binaries for multiple Operating Systems and architectures on the GitHub [releases page](https://github.com/nginx/nginx-prometheus-exporter/releases).
### Homebrew
You can add the NGINX homebrew tap with
```console
brew tap nginx/tap
```
and then install the formula with
```console
brew install nginx-prometheus-exporter
```
### Snap
You can install the NGINX Prometheus Exporter from the [Snap Store](https://snapcraft.io/nginx-prometheus-exporter).
```console
snap install nginx-prometheus-exporter
```
### Scoop
You can add the NGINX Scoop bucket with
```console
scoop bucket add nginx https://github.com/nginx/scoop-bucket.git
```
and then install the package with
```console
scoop install nginx-prometheus-exporter
```
### Nix
First include NUR in your packageOverrides as explained in the [NUR documentation](https://github.com/nix-community/NUR#installation).
Then you can use the exporter with the following command:
```console
nix-shell --packages nur.repos.nginx.nginx-prometheus-exporter
```
or install it with:
```console
nix-env -f '<nixpkgs>' -iA nur.repos.nginx.nginx-prometheus-exporter
```
## Building the Exporter
You can build the exporter using the provided Makefile. Before building the exporter, make sure the following software
is installed on your machine:
- make
- git
- Docker for building the container image
- Go for building the binary
### Building the Docker Image
To build the Docker image with the exporter, run:
```console
make container
```
Note: go is not required, as the exporter binary is built in a Docker container. See the [Dockerfile](build/Dockerfile).
### Building the Binary
To build the binary, run:
```console
make
```
Note: the binary is built for the OS/arch of your machine. To build binaries for other platforms, see the
[Makefile](Makefile).
The binary is built with the name `nginx-prometheus-exporter`.
## Grafana Dashboard
The official Grafana dashboard is provided with the exporter for NGINX. Check the [Grafana
Dashboard](./grafana/README.md) documentation for more information.
## SBOM (Software Bill of Materials)
We generate SBOMs for the binaries and the Docker image.
### Binaries
The SBOMs for the binaries are available in the releases page. The SBOMs are generated using
[syft](https://github.com/anchore/syft) and are available in SPDX format.
### Docker Image
The SBOM for the Docker image is available in the
[DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter),
[GitHub Container registry](https://github.com/nginx/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter),
[Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and
[Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter) repositories. The SBOMs are generated using
[syft](https://github.com/anchore/syft) and stored as an attestation in the image manifest.
For example to retrieve the SBOM for `linux/amd64` from Docker Hub and analyze it using
[grype](https://github.com/anchore/grype) you can run the following command:
```console
docker buildx imagetools inspect nginx/nginx-prometheus-exporter:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
```
## Provenance
We generate provenance for the Docker image and it's available in the
[DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter),
[GitHub Container registry](https://github.com/nginx/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter),
[Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and
[Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter) repositories, stored as an attestation in the
image manifest.
For example to retrieve the provenance for `linux/amd64` from Docker Hub you can run the following command:
```console
docker buildx imagetools inspect nginx/nginx-prometheus-exporter:edge --format '{{ json (index .Provenance "linux/amd64").SLSA }}'
```
## Contacts
We’d like to hear your feedback! If you have any suggestions or experience issues with the NGINX Prometheus Exporter,
please create an issue or send a pull request on GitHub. You can contact us on the [NGINX Community Forums](https://community.nginx.org/).
## Contributing
If you'd like to contribute to the project, please read our [Contributing guide](CONTRIBUTING.md).
## Support
The commercial support is available for NGINX Plus customers when the NGINX Prometheus Exporter is used with NGINX
Ingress Controller.
## License
[Apache License, Version 2.0](LICENSE).
|
