• Stars
    star
    135
  • Rank 269,297 (Top 6 %)
  • Language
    C
  • Created over 10 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An nginx module for collecting stats into Graphite

graphite-nginx-module

An nginx module for collecting location stats into Graphite.

This module is not distributed with the Nginx source. See the installation instructions.

Features

  • Aggregation of location, server or http metrics
  • Calculation of percentiles
  • Sending data to Graphite over UDP or TCP in non-blocking way
  • Sending custom metrics from lua

Version

This document describes graphite-nginx-module v2.3.0 released on 21 August 2018.

Synopsis

http {
    graphite_config prefix=playground server=127.0.0.1;
    server {
        location /foo/ {
            graphite_data nginx.foo;
        }
    }
}

Description

This module use shared memory segment to collect aggregated stats from all workers and send calculated values for last minute to Graphite every 60s (default) over UDP or TCP in non-blocking way. Stats aggegation made on the fly in fixed size buffer allocated on server start and does't affect server performance.

This module is in active use on Mail.Ru Sites (one of largest web-services in Russia) for about a year and considered stable and well-tested.

To collect metrics from nginx core modules (ssl, gzip, upstream) little patch must be applied on nginx source tree. See the installation instructions. You can build this module as a dynamic one, but then you won't be able to collect metrics from nginx core modules (ssl, gzip, upstream) and lua functions.

Directives

graphite_config

syntax: graphite_config key1=<value1> key2=<value2> ... keyN=<valueN>

context: http

Specify global settings for a whole server instance.

Param Required Default Description
prefix path prefix for all graphs
host gethostname() host name for all graphs
server Yes carbon-cache server IP address
protocol udp carbon-cache server protocol (udp or tcp)
port 2003 carbon-cache server port
frequency 60 how often send values to Graphite (seconds)
intervals 1m aggregation intervals, time interval list, vertical bar separator (m - minutes)
params * limit metrics list to track, vertical bar separator
shared 2m shared memory size, increase in case of too small shared memory error
buffer 64k network buffer size, increase in case of too small buffer size error
package 1400 maximum UDP packet size
template template for graph name (default is $prefix.$host.$split.$param_$interval)
error_log path suffix for error logs graphs (*)

(*): works only when nginx_error_log_limiting*.patch is applied to the nginx source code

Example (standard):

http {
    graphite_config prefix=playground server=127.0.0.1;
}

Example (custom):

http {
    graphite_config prefix=playground server=127.0.0.1 intervals=1m|5m|15m params=rps|request_time|upstream_time template=$prefix.$host.$split.$param_$interval;
}

Example (error_log):

http {
    graphite_config prefix=playground server=127.0.0.1 error_log=log;
}

graphite_default_data

syntax: graphite_default_data <path prefix> [params=<params>] [if=<condition>]

context: http, server

Create measurement point in all nested locations. You can use "$location" or "$server" variables which represent the name of the current location and the name of current server with all non-alphanumeric characters replaced with "_." Leading and trailing "_" are deleted.

Example:

   graphite_default_data nginx.$location;

   location /foo/ {
   }

   location /bar/ {
   }

Data for /foo/ will be sent to nginx.foo, data for /bar/ - to nginx.bar. The <params> parameter (1.3.0) specifies list of params to be collected for all nested locations. To add all default params, use *. The <if> parameter (1.1.0) enables conditional logging. A request will not be logged if the condition evaluates to "0" or an empty string.

Example(with $server):

    graphite_default_data nginx.$server.$location

    server {
        server_name foo_host;

        location /foo/ {
        }
    }

    server {
        server_name bar_host;

        location /bar/ {
        }
    }

Data for /foo/ will be sent to nginx.foo_host.foo, data for /bar/ - to nginx.bar_host.bar.

graphite_data

syntax: graphite_data <path prefix> [params=<params>] [if=<condition>]

context: http, server, location, if

Create measurement point in specific location.

Example:

    location /foo/ {
        graphite_data nginx.foo;
    }

The <params> parameter (1.3.0) specifies list of params to be collected for this location. To add all default params, use *. The <if> parameter (1.1.0) enables conditional logging. A request will not be logged if the condition evaluates to "0" or an empty string.

Example:

    map $scheme $is_http { http 1; }
    map $scheme $is_https { https 1; }

    ...

    location /bar/ {
        graphite_data nginx.all.bar;
        graphite_data nginx.http.bar if=$is_http;
        graphite_data nginx.https.bar if=$is_https;
        graphite_data nginx.arg params=rps|request_time;
        graphite_data nginx.ext params=*|rps|request_time;
    }

graphite_param

syntax: graphite_param name=<path> interval=<time value> aggregate=<func>

context: location

Param Required Description
name Yes path prefix for all graphs
interval Yes* aggregation interval, time intrval value format (m - minutes)
aggregate Yes* aggregation function on values
percentile Yes* percentile level

aggregate functions

func Description
sum sum of values per interval
persec sum of values per second (sum divided on seconds in interval)
avg average value on interval
gauge gauge value

Example: see below.

Nginx API for Lua

syntax: ngx.graphite.param(<name>)

Get a link on a graphite parameter name, to use it in place of the name for the functions below. The link is valid up to nginx reload. After getting the link of a parameter, you can still pass the parameter name to the functions below. You can get the link of a parameter multiple times, you'll always get the same object by the same name (a lightuserdata). The function returns false if the parameter specified by name doesn't exist. The function returns nil on link getting errors. Functions access parameters information by link faster than by name.

Available after applying patch to lua-nginx-module. The feature is present in the patch for lua module v0.10.12. See the installation instructions.

syntax: ngx.graphite(<name_or_link>,<value>[,<config>])

Write stat value into aggregator function. Floating point numbers accepted in value.

Available after applying patch to lua-nginx-module. See the installation instructions.

ngx.graphite(name, value, config)

Example:

location /foo/ {
    graphite_param name=lua.foo_sum aggregate=sum interval=1m;
    graphite_param name=lua.foo_rps aggregate=persec interval=1m;
    graphite_param name=lua.foo_avg aggregate=avg interval=1m;
    graphite_param name=lua.foo_gauge aggregate=gauge;

    content_by_lua '
        ngx.graphite("lua.foo_sum", 0.01)
        ngx.graphite("lua.foo_rps", 1)
        ngx.graphite("lua.foo_avg", ngx.var.request_uri:len())
        local foo_gauge_link = ngx.graphite.param("lua.foo_gauge")
        ngx.graphite(foo_gauge_link, 10)
        ngx.graphite(foo_gauge_link, -2)
        ngx.graphite("lua.auto_rps", 1, "aggregate=persec interval=1m percentile=50|90|99")
        ngx.say("hello")
    ';
}

You must either specify the graphite_param command or pass the config argument. If you choose the second option, the data for this graph will not be sent until the first call to ngx.graphite.

Warning: If you do not declare graph using graphite_param command then memory for the graph will be allocated dynamically in module's shared memory. If module's shared memory is exhausted while nginx is running, no new graphs will be created and an error message will be logged.

syntax: ngx.graphite.get(<name_or_link>)

Get value of the gauge param with specified name_or_link.

syntax: ngx.graphite.set(<name>,<value>)

Set value to the gauge param with specified name_or_link.

Params

Param Units Func Description
request_time ms avg total time spent on serving request
bytes_sent bytes avg http response length
body_bytes_sent bytes avg http response body length
request_length bytes avg http request length
ssl_handshake_time ms avg time spent on ssl handsake
ssl_cache_usage % last how much SSL cache used
content_time ms avg time spent generating content inside nginx
gzip_time ms avg time spent gzipping content ob-the-fly
upstream_time ms avg time spent tailking with upstream
upstream_connect_time ms avg time spent on upstream connect (nginx >= 1.9.1)
upstream_header_time ms avg time spent on upstream header (nginx >= 1.9.1)
rps rps sum total requests number per second
keepalive_rps rps sum requests number sent over previously opened keepalive connection
response_2xx_rps rps sum total responses number with 2xx code
response_3xx_rps rps sum total responses number with 3xx code
response_4xx_rps rps sum total responses number with 4xx code
response_5xx_rps rps sum total responses number with 5xx code
response_[0-9]{3}_rps rps sum total responses number with given code
upstream_cache_(miss|bypass|expired|stale|updating|revalidated|hit)_rps rps sum totar responses with a given upstream cache status
lua_time ms avg time spent on lua code

Percentiles

To calculate percentile value for any parameter, set percentile level via /. E.g. request_time/50|request_time/90|request_time/99.

Installation

Requirements

  • nginx: 1.2.0 - 1.14.x
  • lua-nginx-module: 0.8.6 - 0.10.13 (optional)

Build nginx with graphite module

wget 'http://nginx.org/download/nginx-1.9.2.tar.gz'
tar -xzf nginx-1.9.2.tar.gz
cd nginx-1.9.2/

# patch to collect ssl_cache_usage, ssl_handshake_time content_time, gzip_time, upstream_time, upstream_connect_time, upstream_header_time graphs (optional)
patch -p1 < /path/to/graphite-nginx-module/graphite_module_v1_7_7.patch

./configure --add-module=/path/to/graphite-nginx-module

make
make install

Build nginx with graphite dynamic module

wget 'http://nginx.org/download/nginx-1.9.2.tar.gz'
tar -xzf nginx-1.9.2.tar.gz
cd nginx-1.9.2/

./configure --add-dynamic-module=/path/to/graphite-nginx-module

make
make install

Build nginx with lua and graphite modules

wget 'https://github.com/chaoslawful/lua-nginx-module/archive/v0.9.16.tar.gz'
tar -xzf v0.9.16.tar.gz
cd lua-nginx-module-0.9.16/
# patch to add api for sending metrics from lua code (optional)
patch -p1 < /path/to/graphite-nginx-module/lua_module_v0_9_11.patch
cd ..

wget 'http://nginx.org/download/nginx-1.9.2.tar.gz'
tar -xzf nginx-1.9.2.tar.gz
cd nginx-1.9.2/

# patch to collect ssl_cache_usage, ssl_handshake_time content_time, gzip_time, upstream_time, upstream_connect_time, upstream_header_time graphs (optional)
patch -p1 < /path/to/graphite-nginx-module/graphite_module_v1_7_7.patch

./configure \
    --add-module=/path/to/ngx_devel_kit \
    --add-module=/path/to/lua-nginx-module \
    --add-module=/path/to/graphite-nginx-module

make
make install

Instructions on installing lua-nginx-module can be found in documentation on lua-nginx-module.

License

Copyright (c) 2013-2018, Mail.Ru Ltd.

This module is licensed under the terms of the BSD license.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

More Repositories

1

easyjson

Fast JSON serializer for golang.
Go
4,406
star
2

FileAPI

FileAPI — a set of javascript tools for working with files. Multiupload, drag'n'drop and chunked file upload. Images: crop, resize and auto orientation by EXIF.
JavaScript
3,579
star
3

easygo

Tools for building go apps.
Go
671
star
4

icqdesktop.deprecated

C++
461
star
5

go-clickhouse

Golang SQL database driver for Yandex ClickHouse
Go
418
star
6

dbr

Additions to Go's database/sql for super fast performance and convenience. (fork of gocraft/dbr)
Go
174
star
7

fest

javascript templates
JavaScript
128
star
8

jira-scripts

Groovy
113
star
9

tntlua

Tarantool 1.5 Lua stored procedures
Lua
83
star
10

tarantool-authman

Lua
53
star
11

surgemq

Go
19
star
12

jira-plugins-jsincluder

JavaScript
16
star
13

shadowplay

Rust
15
star
14

designsystemsclub

Каталог отечественных компонентных дизайн-систем, реализованных на технологическом уровне. Живые гайдлайны, статьи, презентации, выступления и другие материалы о них.
CSS
15
star
15

jira-plugins-mrimsender

Mail.Ru Agent Notifications JIRA Plugin
Java
13
star
16

sumbur-ruby

sumbur-ruby
Java
12
star
17

ipro-cli

iproto cli tools
C
12
star
18

March

Kotlin
11
star
19

activerecord

Go
10
star
20

confetti

confetti - configuration file parser generator
C
10
star
21

mail-auth-sdk-android

Java
9
star
22

opensource.mail.ru

opensource.mail.ru wiki content
HTML
9
star
23

nocaptcha-php

PHP
8
star
24

imaginelua

Lua
6
star
25

slick-migration

Slick-migration - is a Scala library that helps to maintain compilable migration scripts
Scala
5
star
26

top-mail-ru

PHP
5
star
27

hit-doc

PHP
5
star
28

libzxcvbn

Simple implementation of zxcvbn in C
C
4
star
29

queue-processor

PHP queues processing tool
PHP
4
star
30

inetnums

Python
4
star
31

jira-plugins-commons

Dependency module
Java
4
star
32

nocaptcha-bitrix

CMS Bitrix module for working with Nocaptcha Mail.Ru service
PHP
4
star
33

iproto-ruby

Ruby implementation of Mail.Ru iproto protocol
Ruby
3
star
34

confluence-plugins-utils

Java
3
star
35

mrasender

Tarantool module for sending messages to Mail.Ru Agent
C
3
star
36

nocaptcha-perl

Perl module for working with Nocaptcha Mail.Ru service
Perl
3
star
37

bamboo-plugins-utils

Utils for Bamboo
Java
2
star
38

nocaptcha-python

Python
2
star
39

mail-auth-sdk-ios

Objective-C
2
star
40

VK-Jira-Plugins

1
star
41

quotas

Lua
1
star
42

2kit

1
star
43

skill_cosmo_quest

Python
1
star
44

wdio-redirect-by-pattern-service

TypeScript
1
star
45

tslint-2kit-rules

1
star
46

nocaptcha-wordpress

WordPress module for working with Nocaptcha Mail.Ru service
PHP
1
star
47

clearnet

Kotlin
1
star
48

activerecord-cookbook

Go
1
star