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) 5[![Github All Releases](https://img.shields.io/github/downloads/hnlq715/nginx-vts-exporter/total.svg)](https://github.com/hnlq715/nginx-vts-exporter) 6[![GitHub release](https://img.shields.io/github/release/hnlq715/nginx-vts-exporter.svg)](https://github.com/hnlq715/nginx-vts-exporter) 7[![Go Report Card](https://goreportcard.com/badge/github.com/hnlq715/nginx-vts-exporter)](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