graphite: Модуль NGINX для сбора статистики в Graphite

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

RedHat Enterprise Linux 7, 8, 9 и 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-graphite

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-graphite

Включите модуль, добавив следующее в верхней части файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_graphite_module.so;

Этот документ описывает nginx-module-graphite v4.3, выпущенный 20 января 2023 года.

Модуль nginx для сбора статистики по местоположению в Graphite.

Особенности

Агрегация метрик местоположения, сервера или http
Расчет перцентилей
Отправка данных в Graphite по UDP или TCP неблокирующим образом
Отправка пользовательских метрик из lua

Синопсис

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

Описание

Этот модуль использует сегмент общей памяти для сбора агрегированной статистики от всех рабочих процессов и отправляет рассчитанные значения за последнюю минуту в Graphite каждые 60 секунд (по умолчанию) по UDP или TCP неблокирующим образом. Агрегация статистики происходит на лету в фиксированном буфере, выделенном при запуске сервера, и не влияет на производительность сервера.

Этот модуль активно используется на Mail.Ru Sites (один из крупнейших веб-сервисов в России) уже около года и считается стабильным и хорошо протестированным.

Для сбора метрик из основных модулей nginx (ssl, gzip, upstream) необходимо применить небольшой патч к исходному коду nginx. См. инструкции по установке. Вы можете собрать этот модуль как динамический, но в этом случае вы не сможете собирать метрики из основных модулей nginx (ssl, gzip, upstream) и функций lua.

Директивы

graphite_config

синтаксис: graphite_config key1=<value1> key2=<value2> ... keyN=<valueN>

контекст: http

Укажите глобальные настройки для всего экземпляра сервера.

Параметр	Обязательный	По умолчанию	Описание
prefix			префикс пути для всех графиков
host		gethostname()	имя хоста для всех графиков
server	Да		IP-адрес сервера carbon-cache
protocol		udp	протокол сервера carbon-cache (udp или tcp)
port		2003	порт сервера carbon-cache
frequency		60	как часто отправлять значения в Graphite (секунды)
intervals		1m	интервалы агрегации, список временных интервалов, вертикальный разделитель (`m` - минуты)
params		*	ограничить список метрик для отслеживания, вертикальный разделитель
shared		2m	размер общей памяти, увеличить в случае ошибки `слишком маленькая общая память`
buffer		64k	размер сетевого буфера, увеличить в случае ошибки `слишком маленький размер буфера`
package		1400	максимальный размер UDP-пакета
template			шаблон для имени графика (по умолчанию $prefix.$host.$split.$param_$interval)
error_log			суффикс пути для графиков журналов ошибок (*)

(*): работает только при применении патча nginx_error_log_limiting*.patch к исходному коду nginx

Пример (стандартный):

http {
    graphite_config prefix=playground server=127.0.0.1;
}

Пример (пользовательский):

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;
}

Пример (error_log):

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

graphite_default_data

синтаксис: graphite_default_data <path prefix> [params=<params>] [if=<condition>]

контекст: http, server

Создает измерительную точку во всех вложенных местоположениях. Вы можете использовать переменные "$location" или "$server", которые представляют имя текущего местоположения и имя текущего сервера, где все неалфавитные символы заменены на "_". Ведущие и конечные "_" удаляются.

Пример:

   graphite_default_data nginx.$location;

   location /foo/ {
   }

   location /bar/ {
   }

Данные для /foo/ будут отправлены в nginx.foo, данные для /bar/ - в nginx.bar. Параметр <params> (1.3.0) указывает список параметров, которые будут собраны для всех вложенных местоположений. Чтобы добавить все параметры по умолчанию, используйте *. Параметр <if> (1.1.0) включает условное логирование. Запрос не будет записан, если условие оценивается как "0" или пустая строка.

Пример (с $server):

    graphite_default_data nginx.$server.$location

    server {
        server_name foo_host;

        location /foo/ {
        }
    }

    server {
        server_name bar_host;

        location /bar/ {
        }
    }

Данные для /foo/ будут отправлены в nginx.foo_host.foo, данные для /bar/ - в nginx.bar_host.bar.

graphite_data

синтаксис: graphite_data <path prefix> [params=<params>] [if=<condition>]

контекст: http, server, location, if

Создает измерительную точку в конкретном местоположении.

Пример:

    location /foo/ {
        graphite_data nginx.foo;
    }

Параметр <params> (1.3.0) указывает список параметров, которые будут собраны для этого местоположения. Чтобы добавить все параметры по умолчанию, используйте *. Параметр <if> (1.1.0) включает условное логирование. Запрос не будет записан, если условие оценивается как "0" или пустая строка.

Пример:

    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

синтаксис: graphite_param name=<path> interval=<time value> aggregate=<func>

контекст: location

Параметр	Обязательный	Описание
name	Да	префикс пути для всех графиков
interval	Да*	интервал агрегации, формат значения временного интервала (`m` - минуты)
aggregate	Да*	функция агрегации значений
percentile	Да*	уровень перцентиля

функции агрегации

func	Описание
sum	сумма значений за интервал
persec	сумма значений в секунду (`sum` деленное на секунды в `interval`)
avg	среднее значение за интервал
gauge	значение измерителя

Пример: см. ниже.

Nginx API для Lua

синтаксис: ngx.graphite.param(<name>)

Получите ссылку на имя параметра graphite, чтобы использовать его вместо имени для функций ниже. Ссылка действительна до перезагрузки nginx. После получения ссылки на параметр вы все еще можете передать имя параметра в функции ниже. Вы можете получить ссылку на параметр несколько раз, вы всегда получите один и тот же объект по одному и тому же имени (lightuserdata). Функция возвращает false, если параметр, указанный по имени, не существует. Функция возвращает nil при ошибках получения ссылки. Функции обращаются к информации о параметрах по ссылке быстрее, чем по имени.

Доступно после применения патча к lua-nginx-module. Эта функция присутствует в патче для модуля lua v0.10.12. См. инструкции по установке.

синтаксис: ngx.graphite(<name_or_link>,<value>[,<config>])

Запишите значение статистики в агрегирующую функцию. Числа с плавающей запятой принимаются в value.

Доступно после применения патча к lua-nginx-module. См. инструкции по установке.

ngx.graphite(name, value, config)

Пример:

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")
    ';
}

Вы должны либо указать команду graphite_param, либо передать аргумент config. Если вы выберете второй вариант, данные для этого графика не будут отправлены до первого вызова ngx.graphite.

Предупреждение: Если вы не объявите график с помощью команды graphite_param, память для графика будет выделена динамически в общей памяти модуля. Если общая память модуля исчерпана во время работы nginx, новые графики не будут созданы, и сообщение об ошибке будет записано.

синтаксис: ngx.graphite.get(<name_or_link>)

Получите значение параметра измерителя с указанным name_or_link.

синтаксис: ngx.graphite.set(<name>,<value>)

Установите value для параметра измерителя с указанным name_or_link.

Параметры

Параметр	Единицы	Функция	Описание
request_time	ms	avg	общее время, затраченное на обработку запроса
bytes_sent	bytes	avg	длина http-ответа
body_bytes_sent	bytes	avg	длина тела http-ответа
request_length	bytes	avg	длина http-запроса
ssl_handshake_time	ms	avg	время, затраченное на ssl-рукопожатие
ssl_cache_usage	%	last	сколько SSL-кэша использовано
content_time	ms	avg	время, затраченное на генерацию контента внутри nginx
gzip_time	ms	avg	время, затраченное на сжатие контента на лету
upstream_time	ms	avg	время, затраченное на взаимодействие с upstream
upstream_connect_time	ms	avg	время, затраченное на подключение к upstream (nginx >= 1.9.1)
upstream_header_time	ms	avg	время, затраченное на заголовок upstream (nginx >= 1.9.1)
rps	rps	sum	общее количество запросов в секунду
keepalive_rps	rps	sum	количество запросов, отправленных через ранее открытое соединение keepalive
response_2xx_rps	rps	sum	общее количество ответов с кодом 2xx
response_3xx_rps	rps	sum	общее количество ответов с кодом 3xx
response_4xx_rps	rps	sum	общее количество ответов с кодом 4xx
response_5xx_rps	rps	sum	общее количество ответов с кодом 5xx
response_[0-9]{3}_rps	rps	sum	общее количество ответов с данным кодом
upstream_cache_(miss\|bypass\|expired\|stale\|updating\|revalidated\|hit)_rps	rps	sum	общее количество ответов с данным статусом кэша upstream
lua_time	ms	avg	время, затраченное на выполнение кода lua

Перцентили

Чтобы рассчитать значение перцентиля для любого параметра, установите уровень перцентиля через /. Например, request_time/50|request_time/90|request_time/99.

патч для добавления API для отправки метрик из кода lua (необязательно)

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/

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-graphite.