Skip to content

Commit aced960

Browse files
Dean-CoakleyDean-Coakley
authored
Add documentation for metrics (#182)
* Change urls to use https instead of https
1 parent 268c106 commit aced960

File tree

1 file changed

+145
-28
lines changed

1 file changed

+145
-28
lines changed

‎README.md

Lines changed: 145 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ NGINX Prometheus exporter makes it possible to monitor NGINX or NGINX Plus using
66

77
## Overview
88

9-
[NGINX](http://nginx.org) exposes a handful of metrics via the [stub_status page](http://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://www.nginx.com/products/nginx/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/).
9+
[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://www.nginx.com/products/nginx/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/).
1010

1111
## Getting Started
1212

@@ -20,7 +20,7 @@ If you’d like to use the NGINX Prometheus Exporter with [NGINX Ingress Control
2020

2121
We assume that you have already installed Prometheus and NGINX or NGINX Plus. Additionally, you need to:
2222
* Expose the built-in metrics in NGINX/NGINX Plus:
23-
* For NGINX, expose the [stub_status page](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status) at `/stub_status` on port `8080`.
23+
* 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`.
2424
* For NGINX Plus, expose the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html#api) at `/api` on port `8080`.
2525
* 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`.
2626

@@ -103,32 +103,149 @@ Usage of ./nginx-prometheus-exporter:
103103
Display the NGINX exporter version. (default false)
104104
```
105105
106-
### Exported Metrics
107-
108-
* Common metrics:
109-
* `nginxexporter_build_info` -- shows the exporter build information.
110-
* For NGINX, the following metrics are exported:
111-
* All [stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html) metrics.
112-
* `nginx_up` -- shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one.
113-
114-
Connect to the `/metrics` page of the running exporter to see the complete list of metrics along with their descriptions.
115-
* For NGINX Plus, the following metrics are exported:
116-
* [Connections](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_connections).
117-
* [HTTP](http://nginx.org/en/docs/http/ngx_http_api_module.html#http_).
118-
* [SSL](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_ssl_object).
119-
* [HTTP Server Zones](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_server_zone).
120-
* [Stream Server Zones](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_server_zone).
121-
* [HTTP Upstreams](http://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`.
122-
* [Stream Upstreams](http://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`.
123-
* [Stream Zone Sync](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_zone_sync).
124-
* `nginxplus_up` -- shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one.
125-
* [Location Zones](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_location_zone).
126-
* [Resolver](http://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_resolver_zone).
127-
128-
129-
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_status_module.html#status_zone) and to see upstream related metrics you must configure upstreams with a [shared memory zone](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone).
130-
131-
### Troubleshooting
106+
## Exported Metrics
107+
108+
### Common metrics:
109+
Name | Type | Description | Labels
110+
----|----|----|----|
111+
`nginxexporter_build_info` | Gauge | Shows the exporter build information. | `gitCommit`, `version` |
112+
`nginx_up` | Gauge | Shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one | [] |
113+
114+
### Metrics for NGINX OSS:
115+
#### [Stub status metrics](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html)
116+
Name | Type | Description | Labels
117+
----|----|----|----|
118+
`nginx_connections_accepted` | Counter | Accepted client connections. | [] |
119+
`nginx_connections_active` | Gauge | Active client connections. | [] |
120+
`nginx_connections_handled` | Counter | Handled client connections. | [] |
121+
`nginx_connections_reading` | Gauge | Connections where NGINX is reading the request header. | [] |
122+
`nginx_connections_waiting` | Gauge | Idle client connections. | [] |
123+
`nginx_connections_writing` | Gauge | Connections where NGINX is writing the response back to the client. | [] |
124+
`nginx_http_requests_total` | Counter | Total http requests. | [] |
125+
126+
### Metrics for NGINX Plus:
127+
#### [Connections](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_connections)
128+
Name | Type | Description | Labels
129+
----|----|----|----|
130+
`nginxplus_connections_accepted` | Counter | Accepted client connections | [] |
131+
`nginxplus_connections_active` | Gauge | Active client connections | [] |
132+
`nginxplus_connections_dropped` | Counter | Dropped client connections dropped | [] |
133+
`nginxplus_connections_idle` | Gauge | Idle client connections | [] |
134+
135+
#### [HTTP](https://nginx.org/en/docs/http/ngx_http_api_module.html#http_)
136+
Name | Type | Description | Labels
137+
----|----|----|----|
138+
`nginxplus_http_requests_total` | Counter | Total http requests | [] |
139+
`nginxplus_http_requests_current` | Gauge | Current http requests | [] |
140+
141+
#### [SSL](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_ssl_object)
142+
Name | Type | Description | Labels
143+
----|----|----|----|
144+
`nginxplus_ssl_handshakes` | Counter | Successful SSL handshakes | [] |
145+
`nginxplus_ssl_handshakes_failed` | Counter | Failed SSL handshakes | [] |
146+
`nginxplus_ssl_session_reuses` | Counter | Session reuses during SSL handshake | [] |
147+
148+
#### [HTTP Server Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_server_zone)
149+
Name | Type | Description | Labels
150+
----|----|----|----|
151+
`nginxplus_server_zone_processing` | Gauge | Client requests that are currently being processed | `server_zone` |
152+
`nginxplus_server_zone_requests` | Counter | Total client requests | `server_zone` |
153+
`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` |
154+
`nginxplus_server_zone_discarded` | Counter | Requests completed without sending a response | `server_zone` |
155+
`nginxplus_server_zone_received` | Counter | Bytes received from clients | `server_zone` |
156+
`nginxplus_server_zone_sent` | Counter | Bytes sent to clients | `server_zone` |
157+
158+
#### [Stream Server Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_server_zone)
159+
Name | Type | Description | Labels
160+
----|----|----|----|
161+
`nginxplus_stream_server_zone_processing` | Gauge | Client connections that are currently being processed | `server_zone` |
162+
`nginxplus_stream_server_zone_connections` | Counter | Total connections | `server_zone` |
163+
`nginxplus_stream_server_zone_sessions` | Counter | Total sessions completed | `code` (the response status code. The values are: `2xx`, `4xx`, and `5xx`), `server_zone` |
164+
`nginxplus_stream_server_zone_discarded` | Counter | Connections completed without creating a session | `server_zone` |
165+
`nginxplus_stream_server_zone_received` | Counter | Bytes received from clients | `server_zone` |
166+
`nginxplus_stream_server_zone_sent` | Counter | Bytes sent to clients | `server_zone` |
167+
168+
#### [HTTP Upstreams](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_upstream)
169+
170+
> 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`.
171+
172+
Name | Type | Description | Labels
173+
----|----|----|----|
174+
`nginxplus_upstream_server_state` | Gauge | Current state | `server`, `upstream` |
175+
`nginxplus_upstream_server_active` | Gauge | Active connections | `server`, `upstream` |
176+
`nginxplus_upstream_server_requests` | Counter | Total client requests | `server`, `upstream` |
177+
`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` |
178+
`nginxplus_upstream_server_sent` | Counter | Bytes sent to this server | `server`, `upstream` |
179+
`nginxplus_upstream_server_received` | Counter | Bytes received to this server | `server`, `upstream` |
180+
`nginxplus_upstream_server_fails` | Counter | Number of unsuccessful attempts to communicate with the server | `server`, `upstream` |
181+
`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` |
182+
`nginxplus_upstream_server_header_time` | Gauge | Average time to get the response header from the server | `server`, `upstream` |
183+
`nginxplus_upstream_server_response_time` | Gauge | Average time to get the full response from the server | `server`, `upstream` |
184+
`nginxplus_upstream_server_health_checks_checks` | Counter | Total health check requests | `server`, `upstream` |
185+
`nginxplus_upstream_server_health_checks_fails` | Counter | Failed health checks | `server`, `upstream` |
186+
`nginxplus_upstream_server_health_checks_unhealthy` | Counter | How many times the server became unhealthy (state 'unhealthy') | `server`, `upstream` |
187+
`nginxplus_upstream_keepalives` | Gauge | Idle keepalive connections | `upstream` |
188+
`nginxplus_upstream_zombies` | Gauge | Servers removed from the group but still processing active client requests | `upstream` |
189+
190+
#### [Stream Upstreams](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_upstream)
191+
192+
> 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`.
193+
194+
Name | Type | Description | Labels
195+
----|----|----|----|
196+
`nginxplus_stream_upstream_server_state` | Gauge | Current state | `server`, `upstream` |
197+
`nginxplus_stream_upstream_server_active` | Gauge | Active connections | `server` , `upstream` |
198+
`nginxplus_stream_upstream_server_connections` | Counter | Total number of client connections forwarded to this server | `server`, `upstream` |
199+
`nginxplus_stream_upstream_server_connect_time` | Gauge | Average time to connect to the upstream server | `server`, `upstream`
200+
`nginxplus_stream_upstream_server_first_byte_time` | Gauge | Average time to receive the first byte of data | `server`, `upstream` |
201+
`nginxplus_stream_upstream_server_response_time` | Gauge | Average time to receive the last byte of data | `server`, `upstream` |
202+
`nginxplus_stream_upstream_server_sent` | Counter | Bytes sent to this server | `server`, `upstream` |
203+
`nginxplus_stream_upstream_server_received` | Counter | Bytes received from this server | `server`, `upstream` |
204+
`nginxplus_stream_upstream_server_fails` | Counter | Number of unsuccessful attempts to communicate with the server | `server`, `upstream` |
205+
`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` |
206+
`nginxplus_stream_upstream_server_health_checks_checks` | Counter | Total health check requests | `server`, `upstream` |
207+
`nginxplus_stream_upstream_server_health_checks_fails` | Counter | Failed health checks | `server`, `upstream` |
208+
`nginxplus_stream_upstream_server_health_checks_unhealthy` | Counter | How many times the server became unhealthy (state 'unhealthy') | `server`, `upstream` |
209+
`nginxplus_stream_upstream_zombies` | Gauge | Servers removed from the group but still processing active client connections | `upstream`|
210+
211+
#### [Stream Zone Sync](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_zone_sync)
212+
Name | Type | Description | Labels
213+
----|----|----|----|
214+
`nginxplus_stream_zone_sync_zone_records_pending` | Gauge | The number of records that need to be sent to the cluster | `zone` |
215+
`nginxplus_stream_zone_sync_zone_records_total` | Gauge | The total number of records stored in the shared memory zone | `zone` |
216+
`nginxplus_stream_zone_sync_zone_bytes_in` | Counter | Bytes received by this node | [] |
217+
`nginxplus_stream_zone_sync_zone_bytes_out` | Counter | Bytes sent by this node | [] |
218+
`nginxplus_stream_zone_sync_zone_msgs_in` | Counter | Total messages received by this node | [] |
219+
`nginxplus_stream_zone_sync_zone_msgs_out` | Counter | Total messages sent by this node | [] |
220+
`nginxplus_stream_zone_sync_zone_nodes_online` | Gauge | Number of peers this node is connected to | [] |
221+
222+
#### [Location Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_location_zone)
223+
Name | Type | Description | Labels
224+
----|----|----|----|
225+
`nginxplus_location_zone_requests` | Counter | Total client requests | `location_zone` |
226+
`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` |
227+
`nginxplus_location_zone_discarded` | Counter | Requests completed without sending a response | `location_zone` |
228+
`nginxplus_location_zone_received` | Counter | Bytes received from clients | `location_zone` |
229+
`nginxplus_location_zone_sent` | Counter | Bytes sent to clients | `location_zone` |
230+
231+
#### [Resolver](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_resolver_zone)
232+
Name | Type | Description | Labels
233+
----|----|----|----|
234+
`nginxplus_resolver_name` | Counter | Total requests to resolve names to addresses | `resolver` |
235+
`nginxplus_resolver_srv` | Counter | Total requests to resolve SRV records | `resolver` |
236+
`nginxplus_resolver_addr` | Counter | Total requests to resolve addresses to names | `resolver` |
237+
`nginxplus_resolver_noerror` | Counter | Total number of successful responses | `resolver` |
238+
`nginxplus_resolver_formerr` | Counter | Total number of FORMERR responses | `resolver` |
239+
`nginxplus_resolver_servfail` | Counter | Total number of SERVFAIL responses | `resolver` |
240+
`nginxplus_resolver_nxdomain` | Counter | Total number of NXDOMAIN responses | `resolver` |
241+
`nginxplus_resolver_notimp` | Counter | Total number of NOTIMP responses | `resolver` |
242+
`nginxplus_resolver_refused` | Counter | Total number of REFUSED responses | `resolver` |
243+
`nginxplus_resolver_timedout` | Counter | Total number of timed out request | `resolver` |
244+
`nginxplus_resolver_unknown` | Counter | Total requests completed with an unknown error | `resolver`|
245+
246+
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_status_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).
247+
248+
## Troubleshooting
132249
133250
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.
134251

0 commit comments

Comments
 (0)