README.md
1# nginx-vts-exporter
2
3[](https://travis-ci.org/hnlq715/nginx-vts-exporter)
4[](https://hub.docker.com/r/sophos/nginx-vts-exporter)
5[](https://github.com/hnlq715/nginx-vts-exporter)
6[](https://github.com/hnlq715/nginx-vts-exporter)
7[](https://goreportcard.com/report/github.com/hnlq715/nginx-vts-exporter)
8
9Simple server that scrapes Nginx [vts](https://github.com/vozlt/nginx-module-vts) stats and exports them via HTTP for Prometheus consumption
10
11To support time related histogram metrics, please refer to [hnlq715/nginx-prometheus-metrics](https://github.com/hnlq715/nginx-prometheus-metrics) or [#43](https://github.com/hnlq715/nginx-vts-exporter/issues/43).
12
13## Table of Contents
14* [Dependency](#dependency)
15* [Download](#download)
16* [Compile](#compile)
17 * [build binary](#build-binary)
18 * [build docker image](#build-docker-image)
19* [Run](#run)
20 * [run binary](#run-binary)
21 * [run docker image](#run-docker-image)
22* [Environment variables](#environment-variables)
23* [Metrics](#metrics)
24 * [Server main](#server-main)
25 * [Server zones](#server-zones)
26 * [Filter zones](#filter-zones)
27 * [Upstreams](#upstreams)
28
29## Dependency
30
31* [nginx-module-vts](https://github.com/vozlt/nginx-module-vts)
32* [Prometheus](https://prometheus.io/)
33* [Golang](https://golang.org/)
34
35## Download
36
37Binary can be downloaded from [Releases](https://github.com/hnlq715/nginx-vts-exporter/releases) page.
38
39## Compile
40
41### build binary
42
43``` shell
44make
45```
46
47### build RPM package
48``` shell
49make rpm
50```
51
52### build docker image
53``` shell
54make docker
55```
56
57## Docker Hub Image
58``` shell
59docker pull sophos/nginx-vts-exporter:latest
60```
61It can be used directly instead of having to build the image yourself.
62([Docker Hub sophos/nginx-vts-exporter](https://hub.docker.com/r/sophos/nginx-vts-exporter/))
63
64## Run
65
66### run binary
67``` shell
68nohup /bin/nginx-vts-exporter -nginx.scrape_uri=http://localhost/status/format/json
69```
70
71### run docker
72```
73docker run -ti --rm --env NGINX_STATUS="http://localhost/status/format/json" sophos/nginx-vts-exporter
74```
75
76## Environment variables
77
78This image is configurable using different env variables
79
80Variable name | Default | Description
81------------- | ----------- | --------------
82NGINX_STATUS | http://localhost/status/format/json | Nginx JSON format status page
83METRICS_ENDPOINT | /metrics | Metrics endpoint exportation URI
84METRICS_ADDR | :9913 | Metrics exportation address:port
85METRICS_NS | nginx | Prometheus metrics Namespaces
86
87## Metrics
88
89Documents about exposed Prometheus metrics.
90
91For details on the underlying metrics please see [nginx-module-vts](https://github.com/vozlt/nginx-module-vts#json-used-by-status)
92
93For grafana dashboard please see [nginx-vts-exporter dashboard](https://grafana.com/dashboards/2949)
94
95### Server main
96
97**Metrics details**
98
99Nginx data | Name | Exposed informations
100------------------ | ------------------------------- | ------------------------
101 **Info** | `{NAMESPACE}_server_info` | hostName, nginxVersion, uptimeSec |
102 **Connections** | `{NAMESPACE}_server_connections`| status [active, reading, writing, waiting, accepted, handled]
103
104**Metrics output example**
105
106``` txt
107# Server Info
108nginx_server_info{hostName="localhost", nginxVersion="1.11.1"} 9527
109# Server Connections
110nginx_server_connections{status="accepted"} 70606
111```
112
113### Server zones
114
115**Metrics details**
116
117Nginx data | Name | Exposed informations
118------------------ | ------------------------------- | ------------------------
119 **Requests** | `{NAMESPACE}_server_requests` | code [2xx, 3xx, 4xx, 5xx, total], host _(or domain name)_
120 **Bytes** | `{NAMESPACE}_server_bytes` | direction [in, out], host _(or domain name)_
121 **Cache** | `{NAMESPACE}_server_cache` | status [bypass, expired, hit, miss, revalidated, scarce, stale, updating], host _(or domain name)_
122
123**Metrics output example**
124
125``` txt
126# Server Requests
127nginx_server_requests{code="1xx",host="test.domain.com"} 0
128
129# Server Bytes
130nginx_server_bytes{direction="in",host="test.domain.com"} 21
131
132# Server Cache
133nginx_server_cache{host="test.domain.com",status="bypass"} 2
134```
135
136### Filter zones
137
138**Metrics details**
139
140Nginx data | Name | Exposed informations
141------------------ | --------------------------------- | ------------------------
142 **Requests** | `{NAMESPACE}_filter_requests` | code [2xx, 3xx, 4xx, 5xx and total], filter, filter name
143 **Bytes** | `{NAMESPACE}_filter_bytes` | direction [in, out], filter, filter name
144 **Response time** | `{NAMESPACE}_filter_responseMsec` | filter, filter name
145
146**Metrics output example**
147
148``` txt
149# Filter Requests
150nginx_upstream_requests{code="1xx", filter="country", filterName="BY"} 0
151
152# Filter Bytes
153nginx_upstream_bytes{direction="in", filter="country", filterName="BY"} 0
154
155# Filter Response time
156nginx_upstream_responseMsec{filter="country", filterName="BY"} 99
157```
158
159
160### Upstreams
161
162**Metrics details**
163
164Nginx data | Name | Exposed informations
165------------------ | ----------------------------------- | ------------------------
166 **Requests** | `{NAMESPACE}_upstream_requests` | code [2xx, 3xx, 4xx, 5xx and total], upstream _(or upstream name)_
167 **Bytes** | `{NAMESPACE}_upstream_bytes` | direction [in, out], upstream _(or upstream name)_
168 **Response time** | `{NAMESPACE}_upstream_responseMsec` | backend (or server), in_bytes, out_bytes, upstream _(or upstream name)_
169
170**Metrics output example**
171
172``` txt
173# Upstream Requests
174nginx_upstream_requests{code="1xx",upstream="XXX-XXXXX-3000"} 0
175
176# Upstream Bytes
177nginx_upstream_bytes{direction="in",upstream="XXX-XXXXX-3000"} 0
178
179# Upstream Response time
180nginx_upstream_responseMsec{backend="10.2.15.10:3000",upstream="XXX-XXXXX-3000"} 99
181```
182
){kind=link}
){kind=link}
){kind=link}
){kind=link}