Перейти к содержанию

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

Установка на Debian/Ubuntu

Эти документы относятся к пакету APT nginx-module-graphite, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-graphite
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия            | Компонент | Архитектуры   |
|-------------|-------------------|-----------|---------------|
| debian      | bookworm          | main      | amd64, arm64  |
| debian      | bookworm-mainline | main      | amd64, arm64  |
| debian      | trixie            | main      | amd64, arm64  |
| debian      | trixie-mainline   | main      | amd64, arm64  |
| ubuntu      | focal             | main      | amd64, arm64  |
| ubuntu      | focal-mainline    | main      | amd64, arm64  |
| ubuntu      | jammy             | main      | amd64, arm64  |
| ubuntu      | jammy-mainline    | main      | amd64, arm64  |
| ubuntu      | noble             | main      | amd64, arm64  |
| ubuntu      | noble-mainline    | main      | amd64, arm64  |

Модуль 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 <путь к префиксу> [params=<параметры>] [if=<условие>]

контекст: 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 <путь к префиксу> [params=<параметры>] [if=<условие>]

контекст: 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=<путь> interval=<значение времени> aggregate=<функция>

контекст: location

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

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

функция Описание
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 мс avg общее время, затраченное на обработку запроса
bytes_sent байты avg длина http-ответа
body_bytes_sent байты avg длина тела http-ответа
request_length байты avg длина http-запроса
ssl_handshake_time мс avg время, затраченное на ssl-рукопожатие
ssl_cache_usage % last объем используемого кэша SSL
content_time мс avg время, затраченное на генерацию контента внутри nginx
gzip_time мс avg время, затраченное на упаковку контента в формат gzip
upstream_time мс avg время, затраченное на взаимодействие с upstream
upstream_connect_time мс avg время, затраченное на подключение к upstream (nginx >= 1.9.1)
upstream_header_time мс 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 мс 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/