README.md 6.13 KB
Newer Older
Sophos's avatar
Sophos committed
1
# nginx-vts-exporter
2

3
[![Build Status](https://travis-ci.org/hnlq715/nginx-vts-exporter.svg?branch=master)](https://travis-ci.org/hnlq715/nginx-vts-exporter)
4
[![Docker Pulls](https://img.shields.io/docker/pulls/sophos/nginx-vts-exporter.svg)](https://hub.docker.com/r/sophos/nginx-vts-exporter)
Sophos's avatar
Sophos committed
5 6
[![Github All Releases](https://img.shields.io/github/downloads/hnlq715/nginx-vts-exporter/total.svg)](https://github.com/hnlq715/nginx-vts-exporter)
[![GitHub release](https://img.shields.io/github/release/hnlq715/nginx-vts-exporter.svg)](https://github.com/hnlq715/nginx-vts-exporter)
Sophos's avatar
Sophos committed
7
[![Go Report Card](https://goreportcard.com/badge/github.com/hnlq715/nginx-vts-exporter)](https://goreportcard.com/report/github.com/hnlq715/nginx-vts-exporter)
Sophos's avatar
Sophos committed
8

monktastic's avatar
monktastic committed
9
Simple server that scrapes Nginx [vts](https://github.com/vozlt/nginx-module-vts) stats and exports them via HTTP for Prometheus consumption
liqi's avatar
liqi committed
10

Sophos's avatar
Sophos committed
11 12
To 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).

Sophos's avatar
Sophos committed
13 14 15 16
## Table of Contents
* [Dependency](#dependency)
* [Download](#download)
* [Compile](#compile)
hnlq715's avatar
hnlq715 committed
17 18 19 20 21 22
  * [build binary](#build-binary)
  * [build docker image](#build-docker-image)
* [Run](#run)
  * [run binary](#run-binary)
  * [run docker image](#run-docker-image)
* [Environment variables](#environment-variables)
Sophos's avatar
Sophos committed
23
* [Metrics](#metrics)
Sophos's avatar
Sophos committed
24 25
  * [Server main](#server-main)
  * [Server zones](#server-zones)
26
  * [Filter zones](#filter-zones)
Sophos's avatar
Sophos committed
27 28 29
  * [Upstreams](#upstreams)

## Dependency
30

liqi's avatar
liqi committed
31
* [nginx-module-vts](https://github.com/vozlt/nginx-module-vts)
Sophos's avatar
Sophos committed
32 33 34
* [Prometheus](https://prometheus.io/)
* [Golang](https://golang.org/)

Sophos's avatar
Sophos committed
35
## Download
36

Sophos's avatar
Sophos committed
37
Binary can be downloaded from [Releases](https://github.com/hnlq715/nginx-vts-exporter/releases) page.
38

Sophos's avatar
Sophos committed
39
## Compile
40

hnlq715's avatar
hnlq715 committed
41
### build binary
liqi's avatar
liqi committed
42

Sophos's avatar
Sophos committed
43
``` shell
hnlq715's avatar
hnlq715 committed
44
make
liqi's avatar
liqi committed
45
```
Sophos's avatar
Sophos committed
46

hnlq715's avatar
hnlq715 committed
47 48 49 50 51 52 53 54 55 56 57 58
### build docker image
``` shell
make docker
```

## Docker Hub Image
``` shell
docker pull sophos/nginx-vts-exporter:latest
```
It can be used directly instead of having to build the image yourself.
([Docker Hub sophos/nginx-vts-exporter](https://hub.docker.com/r/sophos/nginx-vts-exporter/))

Sophos's avatar
Sophos committed
59 60
## Run

hnlq715's avatar
hnlq715 committed
61
### run binary
Sophos's avatar
Sophos committed
62 63
``` shell
nohup /bin/nginx-vts-exporter -nginx.scrape_uri=http://localhost/status/format/json
Giancarlo Rubio's avatar
Giancarlo Rubio committed
64 65
```

hnlq715's avatar
hnlq715 committed
66 67
### run docker
```
hnlq715's avatar
hnlq715 committed
68
docker run  -ti --rm --env NGINX_STATUS="http://localhost/status/format/json" sophos/nginx-vts-exporter
hnlq715's avatar
hnlq715 committed
69
```
70

hnlq715's avatar
hnlq715 committed
71
## Environment variables
Sophos's avatar
Sophos committed
72

73
This image is configurable using different env variables
mrmm's avatar
mrmm committed
74

75 76 77 78 79
Variable name | Default     | Description
------------- | ----------- | --------------
NGINX_STATUS |  http://localhost/status/format/json | Nginx JSON format status page
METRICS_ENDPOINT | /metrics  | Metrics endpoint exportation URI
METRICS_ADDR | :9913 | Metrics exportation address:port
80
METRICS_NS | nginx | Prometheus metrics Namespaces
81

Sophos's avatar
Sophos committed
82 83
## Metrics

84 85 86 87 88
Documents about exposed Prometheus metrics.

For details on the underlying metrics please see [nginx-module-vts](https://github.com/vozlt/nginx-module-vts#json-used-by-status)

For grafana dashboard please see [nginx-vts-exporter dashboard](https://grafana.com/dashboards/2949)
Sophos's avatar
Sophos committed
89 90 91 92 93 94 95

### Server main

**Metrics details**

Nginx data         | Name                            | Exposed informations     
------------------ | ------------------------------- | ------------------------
hnlq715's avatar
hnlq715 committed
96
 **Info**          | `{NAMESPACE}_server_info`       | hostName, nginxVersion, uptimeSec |
Sophos's avatar
Sophos committed
97 98 99 100 101
 **Connections**   | `{NAMESPACE}_server_connections`| status [active, reading, writing, waiting, accepted, handled]

**Metrics output example**

``` txt
hnlq715's avatar
hnlq715 committed
102
# Server Info
Sophos's avatar
Sophos committed
103
nginx_server_info{hostName="localhost", nginxVersion="1.11.1"} 9527
Sophos's avatar
Sophos committed
104 105
# Server Connections
nginx_server_connections{status="accepted"} 70606
Giancarlo Rubio's avatar
Giancarlo Rubio committed
106
```
Sophos's avatar
Sophos committed
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130

### Server zones

**Metrics details**

Nginx data         | Name                            | Exposed informations     
------------------ | ------------------------------- | ------------------------
 **Requests**      | `{NAMESPACE}_server_requests`    | code [2xx, 3xx, 4xx, 5xx, total], host _(or domain name)_
 **Bytes**         | `{NAMESPACE}_server_bytes`       | direction [in, out], host _(or domain name)_
 **Cache**         | `{NAMESPACE}_server_cache`       | status [bypass, expired, hit, miss, revalidated, scarce, stale, updating], host _(or domain name)_

**Metrics output example**

``` txt
# Server Requests
nginx_server_requests{code="1xx",host="test.domain.com"} 0

# Server Bytes
nginx_server_bytes{direction="in",host="test.domain.com"} 21

# Server Cache
nginx_server_cache{host="test.domain.com",status="bypass"} 2
```

131 132 133 134
### Filter zones

**Metrics details**

135 136 137 138 139
Nginx data         | Name                              | Exposed informations
------------------ | --------------------------------- | ------------------------
 **Requests**      | `{NAMESPACE}_filter_requests`     | code [2xx, 3xx, 4xx, 5xx and total], filter, filter name
 **Bytes**         | `{NAMESPACE}_filter_bytes`        | direction [in, out], filter, filter name
 **Response time** | `{NAMESPACE}_filter_responseMsec` | filter, filter name
140 141 142 143 144 145 146 147 148 149 150

**Metrics output example**

``` txt
# Filter Requests
nginx_upstream_requests{code="1xx", filter="country", filterName="BY"} 0

# Filter Bytes
nginx_upstream_bytes{direction="in", filter="country", filterName="BY"} 0

# Filter Response time
151
nginx_upstream_responseMsec{filter="country", filterName="BY"} 99
152 153 154
```


Sophos's avatar
Sophos committed
155 156 157 158
### Upstreams

**Metrics details**

159 160 161 162 163
Nginx data         | Name                                | Exposed informations
------------------ | ----------------------------------- | ------------------------
 **Requests**      | `{NAMESPACE}_upstream_requests`     | code [2xx, 3xx, 4xx, 5xx and total], upstream _(or upstream name)_
 **Bytes**         | `{NAMESPACE}_upstream_bytes`        | direction [in, out], upstream _(or upstream name)_
 **Response time** | `{NAMESPACE}_upstream_responseMsec` | backend (or server), in_bytes, out_bytes, upstream _(or upstream name)_
Sophos's avatar
Sophos committed
164 165 166 167 168 169 170 171 172 173 174

**Metrics output example**

``` txt
# Upstream Requests
nginx_upstream_requests{code="1xx",upstream="XXX-XXXXX-3000"} 0

# Upstream Bytes
nginx_upstream_bytes{direction="in",upstream="XXX-XXXXX-3000"} 0

# Upstream Response time
175
nginx_upstream_responseMsec{backend="10.2.15.10:3000",upstream="XXX-XXXXX-3000"} 99
Giancarlo Rubio's avatar
Giancarlo Rubio committed
176
```