Интеграция Nginx с Prometheus для мониторинга

Интеграция Nginx с Prometheus для мониторинга

Разбираем, как настроить нативную отдачу метрик в Nginx, чтобы собирать детальную статистику через Prometheus и визуализировать данные в Grafana.

Зачем мониторить Nginx через Prometheus

Зачем мониторить Nginx через Prometheus

Когда вы только разворачиваете свой первый веб-сервер или даже управляете кластером из нескольких нод, кажется, что стандартных возможностей мониторинга достаточно. Вы смотрите в логи, видите ошибку 502 или 504 и понимаете, что что-то пошло не так. Но когда инфраструктура растёт, а вместе с ней и количество запросов, подход «посмотрю в логи, если что-то сломается» становится тупиковым.

С практической точки зрения, мониторинг должен давать вам предсказуемость. Вы должны знать о проблеме до того, как пользователи начнут писать вам в Telegram.

Проблема стандартных логов

Традиционный способ диагностики — анализ access.log и error.log. Это полезно для расследования конкретного инцидента, например, когда нужно понять, какой именно IP-адрес пытается эксплуатировать уязвимость Canvas API, но как инструмент оперативного мониторинга логи крайне неэффективны.

Во-первых, логи — это дискретные события. Чтобы понять общую картину, вам нужно агрегировать тысячи строк, строить графики и считать процентили. Это требует огромных ресурсов диска и вычислительной мощности, особенно если вы используете сложные парсеры вроде ELK-стека.

Во-вторых, логи не дают мгновенного представления о состоянии системы. Если у вас резко вырос процент ошибок 5xx, в логах вы увидите это только тогда, когда начнете их читать или настроите сложный поиск по тексту. Вы не увидите динамику: был ли это плавный рост или мгновенный скачок, который совпал с деградацией базы данных или нехваткой оперативной памяти.

Для мониторинга состояния инфраструктуры, будь то Borg UI для бэкапов или ваш основной веб-сервер, нужны не записи о событиях, а числовые показатели состояния.

Преимущества метрик в формате Prometheus

Переход от логов к метрикам — это переход от разрозненных фактов к структурированным данным. Prometheus работает по модели pull: он сам заходит на указанный эндпоинт и забирает текущие значения счетчиков.

В случае с Nginx, использование метрик дает несколько ключевых преимуществ:

1. Низкая нагрузка на систему. Вместо записи каждой строки запроса в файл, Nginx просто инкрементирует счетчики в оперативной памяти. Это гораздо дешевле с точки зрения I/O.
2. Математическая точность. Вы получаете не просто «количество ошибок», а возможность вычислить скорость их появления (rate), процентили времени ответа (latency) и другие сложные производные.
3. Готовая интеграция. Метрики в формате Prometheus легко подхватываются системой и превращаются в красивые графики. Если вы уже создавали дашборд для своей домашней лаборатории, то принцип работы с Prometheus будет вам знаком.

Чтобы Prometheus мог забрать данные, Nginx должен их отдать. Поскольку в стандартной сборке Nginx нет встроенного эндпоинта для Prometheus, нам понадобится либо модуль nginx-module-vts, либо использование стороннего экспортера. В следующих разделах мы разберем, как настроить именно нативную отдачу метрик, чтобы получить максимально точную картину происходящего.

Настройка модуля для сбора метрик

Подготовка конфигурации Nginx

Прежде чем приступать к настройке, важно понимать: стандартный Nginx из репозиториев большинства дистрибутивов (Debian, Ubuntu) не умеет отдавать метрики в формате Prometheus «из коробки». Для этого требуется модуль nginx-module-vts или использование сторонних экспортеров. С практической точки зрения, если вы используете Docker, проще всего взять готовый образ, где модуль уже скомпилирован. Если же вы настраиваете всё на «железе» или в виртуальной машине, вам придётся либо собирать Nginx из исходников с поддержкой модуля, либо устанавливать пакет nginx-module-vts.

Я предпочитаю работать с модулем VTS (Virtual Host Traffic Status), так как он даёт гораздо более глубокую детализацию по каждому виртуальному хосту, а не просто общую статистику по серверу. Это критично, когда в вашей домашней лаборатории под одним Nginx крутятся десятки сервисов — от Nextcloud до личных дашбордов.

Сначала убедитесь, что модуль установлен в системе. В Debian/Ubuntu это можно сделать командой:

bashКопировать
sudo apt update
sudo apt install libnginx-mod-http-vts

После установки проверьте, что модуль подгружается. Загляните в директорию /etc/nginx/modules-enabled/. Если там есть соответствующий .conf файл, значит, система увидела модуль.

Создание эндпоинта /metrics

Теперь нужно заставить Nginx отдавать данные. Для этого мы добавим настройки модуля в основной конфиг и создадим отдельный location, который будет слушать запросы от Prometheus.

Во-первых, добавьте инициализацию модуля в блок http вашего файла nginx.conf. Это нужно сделать до того, как вы начнете описывать конкретные server.

nginxКопировать
http {
    # Инициализируем модуль VTS
    vts_install;
    vts_convert_to_prometheus;

    # Остальные настройки (upstream, logging и т. д.)
    ...
}

Во-вторых, создайте эндпоинт. Я рекомендую выносить метрики на отдельный порт или ограничивать доступ к ним по IP, чтобы случайный прохожий не мог собирать статистику о вашем трафике. Если вы планируете развивать свою инфраструктуру, например, создавая дашборд для Homelab с Dashy, безопасность эндпоинтов должна быть в приоритете.

Пример конфигурации для отдельного сервера, который будет отвечать только за метрики:

nginxКопировать
server {
    listen 9113; # Выделяем отдельный порт для мониторинга
    server_name localhost;

    # Ограничиваем доступ: разрешаем только вашему серверу с Prometheus
    # В реальной среде лучше использовать allow <IP_адрес_prometheus>;
    allow 127.0.0.1;
    deny all;

    location /metrics {
        vts_metrics_output; # Команда для генерации метрик в формате Prometheus
    }
}

После внесения изменений обязательно проверьте синтаксис конфигурации:

bashКопировать
sudo nginx -t

Если ошибок нет, перезапустите сервис:

bashКопировать
sudo systemctl restart nginx

Теперь, если вы выполните curl http://localhost:9113/metrics, вы должны увидеть текстовый список метрик, начинающийся с префиксов nginx_. Это именно те данные, которые Prometheus заберёт в свою базу для последующей визуализации. Предсказуемость такой настройки заключается в том, что метрики отделены от основного трафика и не нагружают обработку пользовательских запросов.

Сбор и визуализация данных

Конфигурация Prometheus для скрейпинга

Когда Nginx готов отдавать метрики (например, через модуль nginx-module-vts или сторонний экспортер), следующая задача — научить Prometheus забирать эти данные. В экосистеме мониторинга этот процесс называется скрейпингом.

С практической точки зрения, вам нужно отредактировать основной файл конфигурации Prometheus — обычно это /etc/prometheus/prometheus.yml. Мы добавим новый job, который будет опрашивать наш веб-сервер с заданным интервалом.

Пример настройки в prometheus.yml:

yamlКопировать
scrape_configs:
  - job_name: 'nginx-monitoring'
    # Интервал опроса. Для домашних серверов 15–30 секунд — оптимально.
    scrape_interval: 15s
    # Время, по истечении которого Prometheus пометит цель как упавшую (down).
    scrape_timeout: 10s
    static_configs:
      - targets: ['192.168.1.50:8080'] # IP-адрес вашего Nginx и порт, где висят метрики

Здесь важно соблюдать баланс. Если поставить scrape_interval слишком коротким (например, 1 секунда), вы создадите лишнюю нагрузку на сеть и сам Nginx. Если слишком длинным — пропустите кратковременные всплески трафика или ошибки. Я обычно придерживаюсь 15 секунд: это обеспечивает хорошую детализацию и не превращает мониторинг в DDoS-атаку на собственные сервисы.

После внесения изменений перезапустите сервис Prometheus или отправьте сигнал на перечитывание конфигурации:

bashКопировать
# Если используете systemd
sudo systemctl reload prometheus

Чтобы убедиться, что всё работает, откройте веб-интерфейс Prometheus (по умолчанию порт 9090) и перейдите в раздел Status -> Targets. Если статус цели nginx-monitoring сменился на UP, значит, данные успешно поступают в базу.

Создание дашбордов в Grafana

Сам по себе Prometheus — это отличная база данных временных рядов, но смотреть на «сырые» метрики в консоли неудобно. Для визуализации мы используем Grafana.

Чтобы не тратить время на ручное рисование каждого графика, я рекомендую использовать готовые дашборды из сообщества. Это позволяет сразу получить предсказуемый и понятный результат.

1. Зайдите в интерфейс Grafana.
2. В левом меню выберите Dashboards и нажмите New -> Import.
3. В поле Import via grafana.com введите ID популярного дашборда для Nginx VTS (например, 12708 или 14315).
4. Нажмите Load.
5. В появившемся окне выберите ваш Prometheus в качестве источника данных (Data Source) и нажмите Import.

Если вы хотите собрать дашборд самостоятельно, чтобы он соответствовал вашим задачам (например, если вы создаёте дашборд для домашней лаборатории с помощью Dashy), сосредоточьтесь на следующих ключевых метриках:

• Request Rate (RPS): количество запросов в секунду. Помогает понять общую нагрузку.
• Error Rate (4xx/5xx): процент ошибок. Резкий рост 5xx-х ошибок — первый признак того, что бэкенд «прилёг».
• Latency (Response Time): время ответа сервера. Важно отслеживать не только среднее значение, но и перцентили (p95, p99), чтобы видеть задержки, с которыми сталкиваются отдельные пользователи.
• Connections: количество активных соединений. Помогает выявить утечки ресурсов или аномальную активность.

Для построения графика ошибок в Grafana используйте запрос вида: sum(rate(nginx_http_requests_total{status=~"5.."}[5m])) / sum(rate(nginx_http_requests_total[5m])) * 100

Этот запрос покажет процент ошибок 5xx за последние 5 минут. Настройка таких алертов в Prometheus/Alertmanager — следующий логичный шаг, чтобы не проверять графики вручную, а получать уведомления в Telegram, когда что-то действительно идёт не так.

Обеспечение предсказуемости системы

Обеспечение предсказуемости системы

Когда мы внедряем мониторинг, важно помнить: система мониторинга не должна сама становиться причиной деградации сервиса. Если Prometheus начнет слишком часто запрашивать метрики у Nginx, это создаст лишнюю нагрузку на CPU и увеличит задержки (latency) для реальных пользователей. С практической точки зрения, предсказуемость инфраструктуры зависит от того, насколько изолированы процессы сбора данных от процессов обработки трафика.

Проверка доступности метрик

Прежде чем настраивать сбор данных в Prometheus, нужно убедиться, что Nginx отдает метрики корректно и именно в том формате, который ожидает экспортер. Если вы используете nginx-prometheus-exporter, метрики обычно доступны через отдельный порт, который проксирует данные из модуля stub_status.

Сначала проверьте, что модуль http_stub_status_module собран в вашем бинарном файле Nginx. Выполните команду:

bashКопировать
nginx -V 2>&1 | grep --color http_stub_status_module

Если флаг присутствует, настройте секцию location в конфигурационном файле Nginx (например, в /etc/nginx/conf.d/status.conf). Я предпочитаю ограничивать доступ к этой директории только для локального интерфейса или конкретного IP-адреса экспортера, чтобы не выставлять внутреннюю статистику наружу:

nginxКопировать
server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location /metrics {
        stub_status on;
        allow 127.0.0.1;
        deny all;
    }
}

После внесения изменений проверьте синтаксис и перезапустите сервис:

bashКопировать
sudo nginx -t && sudo systemctl reload nginx

Теперь можно проверить отдачу данных напрямую через curl. Это позволит понять, что именно получит Prometheus:

bashКопировать
curl http://127.0.0.1:8080/metrics

Вы должны увидеть текстовый вывод с текущим количеством активных соединений, обработанных запросов и т. д. Если данные приходят, можно переходить к настройке самого Prometheus.

Оптимизация нагрузки при сборе данных

Частая ошибка — выставлять слишком агрессивный интервал сбора метрик (scrape interval). Если вы будете опрашивать Nginx каждые 1–2 секунды, вы получите очень детальные графики, но при этом создадите постоянный фоновый шум, который будет мешать работе основного приложения.

Для большинства задач в домашней лаборатории или даже в среднем продакшене интервал в 15–30 секунд является оптимальным балансом между точностью и нагрузкой.

В конфигурации Prometheus (prometheus.yml) это настраивается в секции scrape_configs. Чтобы обеспечить предсказуемость, я рекомендую явно задавать scrape_timeout, который должен быть чуть меньше интервала сбора:

yamlКопировать
scrape_configs:
  - job_name: 'nginx-exporter'
    scrape_interval: 30s
    scrape_timeout: 20s
    static_configs:
      - targets: ['localhost:9113'] # Порт, на котором запущен экспортер

Если ваша инфраструктура растет и количество контейнеров увеличивается, стоит обратить внимание на то, как вы визуализируете эти данные. Правильно настроенные алерты помогут вовремя заметить аномалии, прежде чем они станут критичными. Подробнее о том, как структурировать визуализацию всей вашей инфраструктуры, можно прочитать в руководстве Создаём дашборд для Homelab с Dashy.

Также помните о безопасности: если вы планируете использовать метрики для анализа атак или аномального поведения, следите за тем, чтобы логирование не перегружало дисковую подсистему. Это актуально, если вы переходите на более сложные схемы размещения данных, описанные в статье Прощай, данные: полный переход на размещение на своём оборудовании в 2026.

Заключение

Итоговые рекомендации по архитектуре

Настройка экспорта метрик из Nginx — это не просто добавление одной строки в конфигурацию. С практической точки зрения, важно понимать, что нативная отдача метрик (через модуль nginx-module-vts или аналоги) даёт нам прозрачность, которой не хватает при обычном просмотре логов. Мы переходим от разрозненных записей в access.log к структурированным временным рядам.

Если вы строите систему для домашней лаборатории, не пытайтесь сразу внедрять сложный стек с Kubernetes. Для начала достаточно связки Nginx + Prometheus Exporter + Grafana. Это обеспечит предсказуемость: вы всегда будете знать, когда закончилось место на диске под логи или когда резко вырос процент 5xx ошибок.

Когда этот подход перестанет работать

Мониторинг через экспорт метрик отлично справляется с анализом трафика, но у него есть предел. Если ваш Nginx начинает обрабатывать десятки тысяч запросов в секунду, сам процесс сбора и парсинга метрик может начать потреблять заметный объём CPU и RAM.

В таких случаях стоит обратить внимание на следующие моменты:

1. Частота опроса (Scrape Interval). Если вы поставите интервал в 1 секунду, Prometheus будет постоянно нагружать Nginx запросами. Для большинства задач интервала в 15–30 секунд вполне достаточно.
2. Размер метрик. Чем больше виртуальных хостов (server blocks) вы прописываете, тем больше весит страница /metrics.
3. Безопасность. Никогда не оставляйте эндпоинт с метриками открытым для всего интернета. Ограничьте доступ на уровне firewall или через allow/deny в самом Nginx:

nginxКопировать
location /metrics {
    # Разрешаем доступ только для подсети, где крутится Prometheus
    allow 192.168.1.0/24;
    deny all;
    
    # Если используете модуль VTS
    vhost_metrics on;
}

Что делать дальше

После того как вы настроили сбор данных, следующим логичным шагом станет визуализация. Не тратьте время на рисование графиков с нуля — в сообществе уже есть готовые решения. Рекомендую поискать дашборды по запросу «Nginx VTS» на сайте Grafana.

Если ваша инфраструктура растёт и вам нужно видеть не только веб-серверы, но и состояние всей домашней лаборатории, посмотрите наше руководство по созданию дашборда для Homelab с помощью Dashy. Это поможет объединить мониторинг сервисов в единую точку обзора.

Для тех, кто планирует масштабную миграцию своих сервисов на собственное оборудование, полезно заранее изучить вопросы безопасности и долгосрочного планирования, о которых мы писали в статье про переход на размещение на своём оборудовании.

FAQ

Как добавить Nginx в Prometheus?

Чтобы Prometheus начал забирать метрики, его нужно описать в конфигурационном файле prometheus.yml. В секции scrape_configs добавьте новый джоб, указав адрес, по которому Nginx отдает статистику.

Если вы используете стандартный подход с экспортером, это будет выглядеть так:

yamlКопировать
scrape_configs:
  - job_name: 'nginx-metrics'
    static_configs:
      # Укажите IP вашего сервера и порт экспортера
      - targets: ['192.168.1.10:9113']

После внесения изменений не забудьте отправить сигнал SIGHUP процессу Prometheus или перезапустить сервис через systemctl, чтобы настройки вступили в силу:

bashКопировать
sudo systemctl reload prometheus

Влияет ли сбор метрик на производительность?

С практической точки зрения — влияние минимально, если всё настроено правильно. Основная нагрузка ложится на генерацию самой статистики и на сетевой стек при её отдаче.

Если вы используете нативный модуль nginx-module-vts, он собирает данные «на лету», что очень эффективно. Однако стоит учитывать два момента:

1. Частота опроса (scrape interval): Если Prometheus будет запрашивать метрики каждую секунду, это создаст лишнюю нагрузку на CPU. Для домашней лаборатории или небольшого продакшена интервала в 15–30 секунд вполне достаточно.
2. Объём данных: При огромном количестве активных соединений размер страницы с метриками может вырасти.

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

Нужно ли использовать сторонние модули?

Здесь есть два пути: использовать официальный модуль Nginx или сторонние решения вроде nginx-prometheus-exporter.

1. Сторонние экспортеры: Это самый простой путь. Вы запускаете отдельный контейнер или процесс, который опрашивает стандартную страницу stub_status и переводит её в формат, понятный Prometheus. Это не требует пересборки самого Nginx.
2. Нативные модули (например, VTS): Это более профессиональный подход. Модуль nginx-module-vts даёт гораздо больше деталей: распределение по upstream-серверам, детальную статистику по хостам и даже размер передаваемого трафика. Но для этого придётся либо использовать готовые сборки, либо компилировать Nginx самостоятельно.

Если вам нужна предсказуемость и глубокая аналитика, лучше один раз настроить нативный модуль. Если же нужно «здесь и сейчас» — ставьте экспортер. Выбор зависит от того, насколько детальный аудит трафика вам требуется.

Часто задаваемые вопросы

Как метрики Nginx влияют на производительность сервера

Сбор метрик через модуль nginx-module-vts или нативную отдачу статистики потребляет крайне мало ресурсов, так как это всего лишь инкрементальные счётчики в оперативной памяти. Основная нагрузка ложится на процесс сбора данных (scraping) со стороны Prometheus, который делает HTTP-запросы к эндпоинту раз в несколько секунд. Если вы настроите слишком частый интервал опроса (например, чаще 1 секунды), это может создать избыточную нагрузку на сетевой стек и CPU при очень высоком трафике.

Можно ли мониторить Nginx без установки дополнительных модулей

Если вы используете стандартную сборку Nginx, встроенного функционала для отдачи метрик в формате Prometheus в ней нет. В таком случае приходится использовать сторонние решения, например, nginx-exporter, который парсит стандартную страницу stub_status. С практической точки зрения, использование специализированного модуля предпочтительнее, так как он даёт гораздо более глубокую детализацию по HTTP-статусам, объёмам трафика и активным соединениям.

Нужно ли ограничивать доступ к эндпоинту с метриками

Безусловно, эндпоинт, отдающий статистику (например, /metrics), должен быть защищён от внешнего доступа. Если оставить его открытым, любой пользователь сможет увидеть структуру вашего трафика, количество запросов и другие технические детали инфраструктуры. Рекомендую настроить доступ к этому пути только для IP-адреса вашего сервера Prometheus или ограничить его на уровне локальной сети, используя директиву allow и deny в конфигурационном файле Nginx.

В чём разница между мониторингом логов и метрик

Логи — это детальная история каждого конкретного события, которая необходима для расследования причин инцидента (post-mortem). Метрики же предоставляют агрегированные числовые данные, которые позволяют отслеживать общую динамику и состояние системы в реальном времени. Если логи отвечают на вопрос «что именно произошло с этим пользователем», то метрики отвечают на вопрос «насколько сильно деградировала производительность всего сервиса».