Если у вас в продакшене крутится Nginx, вопрос «что и как мониторить» быстро становится не риторическим. Классические графики CPU/Disk/Net говорят о железе, но не о живых HTTP-потоках: сколько запросов, где затык, почему растут 5xx и проседают апстримы. Для Prometheus существует два основных подхода: использовать официальный nginx-prometheus-exporter со встроенным модулем stub_status или подключить модуль VTS (Virtual Host Traffic Status) и отдать расширенные метрики через отдельный экспортер. В статье сравним эти варианты без фанатизма, посмотрим на типовые конфиги и разберём подводные камни.
Кратко о подходах
Оба пути решают одну задачу — получить метрики Nginx в формате Prometheus. Отличается источник данных и глубина метрик.
- nginx-prometheus-exporter + stub_status: лёгкая установка, минимум зависимостей, базовые метрики по соединениям и запросам. Подходит как «быстрый старт» и для простых стендов.
- VTS (ngx_http_vhost_traffic_status) + VTS-экспортер: больше деталей — по виртуальным хостам, апстримам, кэшу, кодам ответов. Требует модуля в Nginx и отдельного экспортера, более сложная эксплуатация.
Что такое nginx-prometheus-exporter
Это процесс-«прокси»: он периодически опрашивает Nginx по stub_status (или API NGINX Plus) и отдаёт преобразованные метрики в формате Prometheus. Для open-source Nginx из коробки доступен только stub_status — компактная сводка по соединениям и количеству запросов.
Ключевые метрики при работе со stub_status:
nginx_connections_active,nginx_connections_reading,nginx_connections_writing,nginx_connections_waitingnginx_connections_accepted,nginx_connections_handlednginx_http_requests_total— общее количество запросов
Важный плюс — не нужно собирать Nginx с внешними модулями. Минус — метрики агрегированные, без разрезов по серверным именам, локациям, апстримам и кодам ответов.
Что такое VTS (Virtual Host Traffic Status)
VTS — динамический модуль для Nginx (чаще в репозиториях как vhost_traffic_status), который собирает расширенную статистику и отдаёт её в JSON. На основе этого JSON работает отдельный VTS-экспортер, преобразуя данные в Prometheus-метрики.
Что даёт VTS:
- Разрезы по серверным блокам, именам хостов и локациям (при желании).
- Статистика по апстримам: активные/неактивные, время ответа, коды ответов, трафик.
- Поддержка статуса кэша (если используете proxy_cache) и распределение по статусам HTTP.
- Shared-memory зона для счётчиков — переживает перезагрузку (reload), но обнуляется при рестарте процесса.
Плюс — богатые метрики, минус — зависимость от внешнего модуля и повышенная сложность настройки и эксплуатации. В некоторых дистрибутивах модуль доступен как отдельный пакет, в других может понадобиться сборка или использование сборок из альтернативных репозиториев.
Сравнение по ключевым критериям
1) Установка и совместимость
- Exporter + stub_status:
stub_statusприсутствует в большинстве пакетов Nginx. Нужен только конфиг локации и бинарник экспортера. Работает практически везде, в контейнерах и на bare-metal. - VTS: требуется модуль. На Debian/Ubuntu часто доступен пакет с префиксом
libnginx-mod-http-vhost-traffic-status. На других системах может понадобиться сборка или использование сторонней сборки. Плюс нужен VTS-экспортер.
2) Глубина и количество метрик
- Exporter + stub_status: основные показатели по соединениям и суммарным запросам. Этого хватает для базовой доступности и трендов нагрузки. Не даёт видимости по апстримам и кодам ответа.
- VTS: детальная видимость — HTTP-коды, апстримы, серверные зоны, кэш. Можно строить SLI/SLO, отслеживать деградацию конкретных сервисов за балансировщиком, находить «тяжёлые» виртуальные хосты.
3) Кардинальность меток и нагрузка на Prometheus
- Exporter + stub_status: очень низкая кардинальность, минимум серий — дешёво и сердито.
- VTS: легко «положить» хранилище метрик, если бездумно расширять разрезы. Каждое имя хоста, локация, апстрим и код ответа множат число метрик. Нужна дисциплина: отбирать нужные лейблы и аккуратно включать фильтры.
4) Накладные расходы и производительность
- Exporter + stub_status: запрос к очень лёгкой странице статуса, парсинг простого ответа — накладные расходы обычно пренебрежимо малы.
- VTS: сбор детальной статистики требует больше работы на каждом запросе и дополнительной памяти в shared zone. На умеренных нагрузках это, как правило, приемлемо; на сверхнагруженных фронтах — измеряйте и будьте готовы отключать избыточные разрезы.
5) Безопасность
- В обоих случаях страницу статуса надо изолировать: слушать только на
127.0.0.1или закрывать поallow/deny, можно повесить базовую авторизацию, если требуется диагностика через браузер. - Экспортер должен ходить локально — не раскрывайте статус наружу. Для продвинутых сценариев используйте отдельный listen на localhost.
6) Обслуживание и обновления
- Exporter + stub_status: минимум подвижных частей. При обновлении Nginx почти ничего не ломается.
- VTS: следите за совместимостью модуля с вашей версией Nginx. Иногда релизы Nginx меняют API модулей, и модуль нужно обновлять.
7) Поведение при reload/restart
- stub_status: счётчики привязаны к процессу. При reload числа продолжают расти, при полном рестарте — обнуляются. Используйте функции
rate()в PromQL. - VTS: данные лежат в shared memory зоне модуля — переживают reload, обнуляются на полный рестарт демона или пересоздание зоны.
8) Контейнеры и Kubernetes
- Exporter + stub_status: ставится как sidecar или отдельный deployment, минимальные требования.
- VTS: образ Nginx должен содержать модуль, или используйте сборки, где модуль уже включён. Это усложняет базовый образ и пайплайн.
Если метрики и экспортеры выносите на отдельный инстанс, удобно поднять их на VDS с ограниченным доступом и системной изоляцией. Для быстрой навигации по хостингу и удобного управления посмотрите наш обзор панелей для серверов: сравнение популярных панелей для VDS.
Практика: быстрый старт с nginx-prometheus-exporter и stub_status
Включим stub_status на локальном интерфейсе и поднимем экспортер.
1) Конфигурация Nginx
# /etc/nginx/conf.d/stub_status.conf
server {
listen 127.0.0.1:8080;
server_name localhost;
location /stub_status {
stub_status on;
allow 127.0.0.1;
deny all;
}
}
Перезагрузите конфиг:
nginx -t
systemctl reload nginx2) Запуск экспортера (systemd)
# /etc/systemd/system/nginx-prometheus-exporter.service
[Unit]
Description=NGINX Prometheus Exporter
After=network.target
[Service]
Type=simple
User=nobody
Group=nobody
ExecStart=/usr/local/bin/nginx-prometheus-exporter -nginx.scrape-uri=http://127.0.0.1:8080/stub_status -telemetry.address=0.0.0.0:9113 -telemetry.endpoint=/metrics
Restart=always
RestartSec=2
[Install]
WantedBy=multi-user.target
Обратите внимание: строка ExecStart должна быть одной строкой. Если нужно читабельно разнести аргументы, используйте EnvironmentFile и подставляйте переменные.
Запустите сервис:
systemctl daemon-reload
systemctl enable --now nginx-prometheus-exporter.service3) Scrape-конфиг для Prometheus
# fragment of prometheus.yml
scrape_configs:
- job_name: nginx
static_configs:
- targets: ['127.0.0.1:9113']
Далее проверьте графики: соединения, скорость запросов через rate(nginx_http_requests_total[1m]). Базовые алёрты на рост 5xx лучше строить по логам или VTS, потому что stub_status коды ответа не различает.
Практика: расширенный мониторинг через VTS
План действий: установить модуль, включить зону VTS, отдать JSON и подключить VTS-экспортер.
1) Установка модуля
В некоторых дистрибутивах модуль доступен из коробки как динамический. После установки пакета удостоверьтесь, что модуль подхватывается через load_module в общем конфиге. Если модуль не доступен, используйте сборку с модулем или соберите самостоятельно в соответствии с политикой вашей инфраструктуры.
2) Конфигурация VTS в Nginx
# /etc/nginx/nginx.conf (фрагмент в верхнем уровне)
load_module modules/ngx_http_vhost_traffic_status_module.so;
http {
vhost_traffic_status_zone;
# По умолчанию vts будет собирать метрики по server{};
# Дополнительно можно включить фильтры, но осторожно с кардинальностью.
}
Добавим эндпоинт статуса на localhost:
# /etc/nginx/conf.d/vts_status.conf
server {
listen 127.0.0.1:8081;
server_name localhost;
location /status {
vhost_traffic_status_display;
vhost_traffic_status_display_format json;
allow 127.0.0.1;
deny all;
}
}
Тест и перезагрузка:
nginx -t
systemctl reload nginx3) Экспортер для VTS (systemd)
VTS-экспортер — отдельный процесс, который опрашивает JSON и выдаёт метрики Prometheus.
# /etc/systemd/system/nginx-vts-exporter.service
[Unit]
Description=NGINX VTS Prometheus Exporter
After=network.target
[Service]
Type=simple
User=nobody
Group=nobody
ExecStart=/usr/local/bin/nginx-vts-exporter -nginx.scrape_uri=http://127.0.0.1:8081/status/format/json -telemetry.addr=:9913 -telemetry.path=/metrics
Restart=always
RestartSec=2
[Install]
WantedBy=multi-user.target
Запуск:
systemctl daemon-reload
systemctl enable --now nginx-vts-exporter.service4) Scrape-конфиг для Prometheus
# fragment of prometheus.yml
scrape_configs:
- job_name: nginx-vts
static_configs:
- targets: ['127.0.0.1:9913']
Теперь у вас появятся метрики вида nginx_vts_server_requests_total, nginx_vts_upstream_requests_total, nginx_vts_upstream_response_seconds с лейблами по серверным именам, апстримам и кодам ответа. Это позволяет строить SLI по конкретным сервисам за Nginx, искать деградацию апстримов и измерять долю ошибок.
Производительность и типичные ошибки
- Частота опроса: разумный интервал 15–30 секунд. Слишком частый опрос увеличивает overhead и объём метрик.
- Кардинальность VTS: не включайте детальные фильтры (например, по локациям), если реально не используете эти графики.
- Изоляция эндпоинта: держите статус на
127.0.0.1. Если нужен доступ снаружи — ограничьтеallow/denyи при необходимости включите базовую авторизацию. - Падение экспортера: чаще всего это неверный
scrape_uriили недоступность локального порта. Проверьте логи и доступность локации curl-ом на локалхосте. - Обнуление счётчиков: это норма при рестарте процесса. Стройте графики через
rate(), алёрты — черезincrease()и процентные доли.
Минимальные алёрты (PromQL)
# Рост 5xx по VTS (за 5 минут) больше 1% от всех запросов
sum by (server) (increase(nginx_vts_server_requests_total{code=~"5.."}[5m]))
/
sum by (server) (increase(nginx_vts_server_requests_total[5m]))
> 0.01
# Высокая доля 4xx на апстриме (за 10 минут) больше 5%
sum by (upstream) (increase(nginx_vts_upstream_requests_total{code=~"4.."}[10m]))
/
sum by (upstream) (increase(nginx_vts_upstream_requests_total[10m]))
> 0.05
# Перегрузка по активным соединениям (stub_status)
nginx_connections_active > 10000
Когда выбирать каждый вариант
Нет универсального ответа. Выбор зависит от того, насколько глубокую наблюдаемость вы хотите получить и сколько усилий готовы потратить на сопровождение.
- Берите nginx-prometheus-exporter + stub_status, если нужен быстрый, надёжный и простой мониторинг: жив ли фронт, как растёт трафик, насколько много соединений. Отлично для минимальных стендов, статики, простых API-шлюзов.
- Берите VTS + VTS-экспортер, если важны разрезы по апстримам, кодам ответов и виртуальным хостам: микросервисы, сложные балансировки, наличие кэша. Будьте готовы контролировать кардинальность и обновления модуля.
- Если у вас NGINX Plus, логично использовать официальный экспортер в режиме опроса API Plus — получите богатые метрики без внешних модулей.
Практические советы по эксплуатации
- Храните экспортёры под systemd с рестартом и health-логикой. Следите за их RAM/CPU в тех же Prometheus-мониторингах.
- Готовьте отдельные dashboards: базовый (stub_status) и расширенный (VTS). Так проще разделить ответственность и ускорить онбординг.
- Для «тяжёлых» инсталляций VTS, где много хостов и апстримов, полезно сегментировать метрики по инстансам и группам сервисов, чтобы не раздувать общий TSDB.
- Если меняете конфиг и метрики, заранее договоритесь об именовании лейблов и стабильности контрактов, иначе поломаете алёрты и панели.
- Для безопасного вынесения балансировщиков и мониторинга на отдельные инстансы используйте VDS — проще изолировать ресурсы и доступ.
Итоги
Экспортер со stub_status — это простота, надёжность и нулевой порог входа. VTS — детальная наблюдаемость, но с ценой в виде большего числа метрик, зависимости от модуля и необходимости дисциплины. Для большинства минимальных и средних инсталляций разумно начать со stub_status, а затем добавлять VTS точечно, где действительно нужны разрезы по апстримам и кодам ответов. Такой путь экономит ресурсы, сохраняет простоту эксплуатации и даёт нужную глубину там, где она окупается.
