Настройка экспорта метрик Nginx в Prometheus

Настройка экспорта метрик Nginx в Prometheus

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

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

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

Когда я только начинал администрировать серверы, мониторинг веб-сервера сводился к проверке того, отвечает ли порт 80 или 443. Но с ростом инфраструктуры — будь то пара виртуальных машин или кластер на Proxmox — становится понятно: просто знать, что сервис «жив», недостаточно. Вам нужно понимать, сколько соединений держит сервер, как распределяется нагрузка по upstream-серверам и нет ли аномального роста ошибок 5xx.

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

Проблема сторонних модулей

Раньше стандартным подходом было использование сторонних модулей, таких как nginx-module-exporter. Идея проста: запустить отдельный процесс, который опрашивает Nginx через модуль stub_status и отдает данные в формате, понятном Prometheus.

С практической точки зрения у такого подхода есть несколько минусов:

1. Лишнее звено в цепи. У вас появляется дополнительный сервис (экспортер), который сам требует ресурсов, мониторинга и настройки. Если экспортер упадет, вы не узнаете, что Nginx работает исправно.
2. Сложность обновления. При обновлении Nginx или самого экспортера можно столкнуться с несовместимостью версий или проблемами при сборке из исходников, если модуль требует специфической компиляции.
3. Потеря контекста. Сторонние инструменты часто дают лишь поверхностную картину, не позволяя глубоко заглянуть в специфичные параметры конфигурации.

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

Преимущества прямой интеграции

Нативная интеграция (через встроенный модуль stub_status) позволяет получать ключевые показатели напрямую от самого веб-сервера. Это обеспечивает ту самую предсказуемость, к которой я всегда стремлюсь в своих конфигурациях.

Основные преимущества:

• Минимальный оверхед. Вы используете штатный функционал Nginx. Это не нагружает CPU и не требует установки тяжеловесного ПО.
• Надёжность. Метрики доступны до тех пор, пока работает сам Nginx. Нет риска, что «прослойка» в виде экспортера решит, что всё в порядке, когда сервис на самом деле лежит.
• Простота конфигурации. Вам не нужно ничего компилировать. Достаточно добавить несколько строк в конфиг.

Для начала работы убедитесь, что у вас включен модуль http_stub_status_module. Проверить это можно, выполнив команду:

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

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

nginxКопировать
server {
    listen 127.0.0.1:8080; # Слушаем только на localhost для безопасности
    server_name localhost;

    location /metrics {
        stub_status on;
        access_log off; # Отключаем логи, чтобы не забивать диск при каждом опросе Prometheus
        allow 127.0.0.1; # Разрешаем доступ только локально
        deny all;        # Запрещаем всем остальным
    }
}

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

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

Включение модуля stub_status

Для того чтобы Prometheus мог забирать данные, Nginx должен начать их отдавать. Самый простой и надёжный способ сделать это без установки сторонних модулей — использовать встроенный модуль ngx_http_stub_status_module. Он не даёт глубокой аналитики по конкретным URL, но предоставляет базовые показатели: количество активных соединений, принятых и обработанных запросов, а также количество текущих соединений. Для мониторинга здоровья сервиса этого обычно достаточно.

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

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

Если в выводе вы видите --with-http_stub_status_module, значит, всё в порядке. Если нет — придётся пересобирать пакет из исходников, что в современных дистрибутивах вроде Debian или Ubuntu встречается редко, так как модуль обычно включен по умолчанию.

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

Пример конфигурации для файла /etc/nginx/sites-available/metrics.conf:

nginxКопировать
server {
    # Слушаем на отдельном IP или порту, если это возможно
    listen 127.0.0.1:8080;
    server_name localhost;

    location /metrics {
        stub_status on;
        access_log off; # Отключаем логирование запросов к метрикам, чтобы не раздувать диски
        ```

Здесь `stub_status on;` — это и есть команда на включение модуля. Я также добавил `access_log off;`, потому что Prometheus будет опрашивать этот эндпоинт каждые несколько секунд. Если оставить логирование включённым, ваш `access.log` быстро превратится в бесконечный поток однотипных записей, что только мешает анализу реальных ошибок.

### Настройка прав доступа к метрикам

Открывать эндпоинт `/metrics` всему интернету — плохая идея. Любой желающий сможет увидеть статистику нагрузки на ваш сервер, что является лишней информацией для посторонних. С точки зрения безопасности, доступ к этим данным должен быть максимально ограничен.

Если ваш Prometheus и Nginx работают на одной машине, проще всего ограничить доступ через `listen 127.0.0.1`. В этом случае эндпоинт будет доступен только локально. Если же Prometheus развёрнут на другой ноде в вашей домашней лаборатории, нужно разрешить доступ только с IP-адреса этого сервера.

Для этого используйте директиву `allow` и `deny`. Отредактируйте блок `location`, который мы создали ранее:

```nginx
    location /metrics {
        stub_status on;
        access_log off;

        # Разрешаем доступ только для Prometheus
        allow 192.168.1.50; # IP вашего сервера с Prometheus
        allow 127.0.0.1;    # Локальный доступ
        deny all;           # Запрещаем всем остальным
    }

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

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

Если проверка прошла успешно, перезапустите Nginx, чтобы изменения вступили в силу:

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

С практической точки зрения, такой подход гарантирует, что метрики не станут источником лишней информации. Это похоже на то, как мы настраиваем доступ к критически важным интерфейсам, например, когда изучаем Borg UI: Веб-интерфейс для BorgBackup или настраиваем защищённые дашборды, как описано в руководстве по Dashy.

Теперь, если вы выполните curl http://127.0.0.1:8080/metrics, вы должны увидеть что-то вроде этого:

textКопировать
Active connections: 2 
server accepts handled requests
 15 15 12 
Reading: 0 Writing: 1 Waiting: 1 

Эти цифры — фундамент, на котором мы построим полноценный мониторинг.

Настройка Prometheus для сбора данных

Конфигурация scrape_configs

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

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

Откройте файл конфигурации (обычно он лежит в /etc/prometheus/prometheus.yml) и добавьте новый джоб. Пример настройки для одного экземпляра Nginx:

yamlКопировать
scrape_configs:
  # Существующие конфиги (например, prometheus-self-monitoring) ...

  - job_name: 'nginx-metrics'
    # Интервал сбора данных. Для Nginx 15–30 секунд обычно достаточно.
    scrape_interval: 15s
    # Время ожидания ответа от эндпоинта
    scrape_timeout: 10s
    static_configs:
      - targets: ['192.168.1.50:9113'] # IP-адрес вашего сервера с Nginx
        labels:
          instance: 'nginx-main'
          env: 'production'

Если вы используете Docker для развёртывания инфраструктуры, вместо статического IP лучше использовать имя контейнера в рамках одной сети.

Обратите внимание на поле labels. Я всегда рекомендую добавлять метки вроде env или role. Это помогает в будущем не только фильтровать данные в Grafenа, но и строить сложные запросы в PromQL, когда количество ваших сервисов перевалит за десяток. Если вы только начинаете строить свою инфраструктуру, рекомендую также изучить материал про то, как создать дашборд для домашней лаборатории, чтобы понимать, какие именно метрики стоит выводить на экран в первую очередь.

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

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

Во-первых, проверьте, что Prometheus подхватил изменения. Это можно сделать через веб-интерфейс: перейдите в раздел Status -> Targets. Если всё настроено верно, вы увидите nginx-metrics в списке со статусом UP. Если статус DOWN, Prometheus напишет причину ошибки (например, connection refused или context deadline exceeded).

Во-вторых, проверьте сам эндпоинт с помощью curl. Это позволит исключить проблемы на стороне сети или прав доступа. Выполните команду с той машины, где запущен Prometheus:

bashКопировать
# Замените IP и порт на ваши актуальные данные
curl -v http://192.168.1.50:9113/metrics

В ответе вы должны увидеть текстовый список метрик, начинающихся с префиксов вроде nginx_. Если вы получили 403 Forbidden или 404 Not Found, значит, проблема в конфигурации самого Nginx или в ограничениях доступа (например, в allow/deny директивах).

Если вы столкнулись с тем, что метрики отдаются, но Prometheus их не видит, проверьте логи системного юнита. Я всегда использую journalctl, чтобы быстро понять, что пошло не так:

bashКопировать
# Просмотр логов Prometheus на предмет ошибок сбора данных
sudo journalctl -u prometheus -f

Помните: предсказуемость системы начинается с уверенности в том, что каждый компонент работает согласно протоколу. Только после успешного прохождения этих проверок можно переходить к визуализации в Grafana.

Визуализация в Grafana

Выбор подходящего дашборда

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

Самый популярный вариант — это дашборды от Grafana Labs. Для Nginx (если вы используете стандартный nginx-prometheus-exporter) лучше всего подходят шаблоны, которые умеют корректно работать с метриками запросов, ответов и ошибок.

Чтобы быстро развернуть визуализацию, выполните следующие шаги:

1. Откройте Grafana и перейдите в раздел Dashboards $\rightarrow$ Import.
2. Введите ID популярного дашборда (например, 12708 или 14905) и нажмите Load.
3. Выберите ваш Prometheus в качестве источника данных (Data Source).

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

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

Создание кастомных панелей для трафика

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

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

Для создания такой панели используйте следующий запрос в режиме Code в редакторе Grafana:

promqlКопировать
# Считаем количество запросов по статус-кодам за последние 5 минут
sum(rate(nginx_http_requests_total{status=~"5.."}[5m])) by (status)

Этот запрос сгруппирует все ошибки сервера (500, 502, 503, 504) и покажет их динамику. Если график резко пошёл вверх — проблема в бэкенде или сетевой связности.

Во-вторых, важно отслеживать объем переданного трафика (throughput). Это помогает понять, не упирается ли канал в физическое ограничение. Для этого создайте панель типа Time series с запросом:

promqlКопировать
# Суммарная скорость передачи данных (в байтах в секунду)
sum(rate(nginx_network_bytes_total[5m]))

Чтобы данные были читаемыми, в настройках панели (Standard options $\rightarrow$ Unit) выберите Data rate $\rightarrow$ bytes/sec. Grafana сама переведёт значения в КБ/с, МБ/с или ГБ/с.

С точки зрения системного администрирования, я советую не ограничиваться только графиками. Хороший мониторинг должен быть связан с системой оповещений. Если вы видите, что трафик вырос, а нагрузка на CPU при этом не изменилась, стоит проверить, не стали ли запросы «тяжёлыми» или не атакует ли вас кто-то с попыткой эксплуатации уязвимостей (например, подобных уязвимости Canvas API).

Настройка кастомных панелей требует времени, но именно они превращают набор цифр в понятный инструмент для принятия решений.

Заключение

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

Настройка экспорта метрик Nginx — это не просто добавление одной строки в конфиг, а создание фундамента для предсказуемости вашей инфраструктуры. Если вы настроили сбор данных через nginx-module-vts или нативный модуль, вы получаете возможность видеть не только общую нагрузку на процессор, но и конкретные показатели: количество активных соединений, распределение по статус-кодам и нагрузку на upstream-серверы.

С практической точки зрения, я рекомендую не ограничиваться базовым сбором. Настройте алертинг в Prometheus через Alertmanager так, чтобы при резком скачке 5xx ошибок или падении количества запросов в секунду (RPS) вы получали уведомление раньше, чем пользователи начнут жаловаться.

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

Важно понимать ограничения. Нативная интеграция или использование модулей вроде VTS отлично справляются с мониторингом трафика, но они не заменяют полноценный аудит безопасности. Если вы видите странные паттерны в логах, которые могут указывать на попытки эксплуатации уязвимостей, одного Prometheus будет мало. В таких случаях стоит проводить более глубокий анализ, например, изучая уязвимость Canvas API, чтобы понимать векторы атак на веб-приложения.

Также стоит учитывать, что при росте количества микросервисов и контейнеров классический подход с опросом каждого экземпляра Nginx может стать избыточным. В больших кластерах Kubernetes лучше переходить к модели Service Discovery, чтобы Prometheus автоматически находил новые ноды.

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

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

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

FAQ

Как Prometheus узнаёт об изменениях в Nginx?

Prometheus не следит за Nginx в реальном времени, как это делает какой-нибудь сервис уведомлений. Он работает по модели pull: сам опрашивает заданные цели (targets) через определённые интервалы времени.

Чтобы это работало, в конфигурационном файле prometheus.yml должен быть описан соответствующий job. Если вы добавили новый сервер в свою домашнюю лабораторию, вам нужно вручную или через Ansible обновить конфиг Prometheus, чтобы он начал «стучаться» на endpoint Nginx.

Пример типичного блока в prometheus.yml:

yamlКопировать
scrape_configs:
  - job_name: 'nginx-metrics'
    scrape_interval: 15s # Как часто опрашиваем сервер
    static_configs:
      - targets: ['192.168.1.50:9113'] # IP вашего сервера с экспортером

Если вы планируете масштабировать инфраструктуру, лучше смотреть в сторону Borg UI: Веб-интерфейс для BorgBackup — Полное руководство, где описаны принципы управления бэкапами, что также требует системного подхода к мониторингу.

Нужно ли устанавливать nginx-exporter?

Если мы говорим о нативной интеграции через модуль ngx_http_stub_status_module, то сам Nginx не отдает метрики в формате, который понимает Prometheus. Он отдает их в текстовом виде, предназначенном для человека.

Поэтому вам в любом случае понадобится прослойка — экспортер. Он забирает данные из модуля stub_status и переводит их в формат Prometheus (key-value пары). С практической точки зрения, установка nginx-prometheus-exporter в Docker-контейнере — самый предсказуемый вариант.

Сначала убедитесь, что в конфиге Nginx включен статус:

nginxКопировать
server {
    listen 8080;
    location /metrics {
        stub_status; # Включает базовую статистику
        allow 127.0.0.1; # Разрешаем доступ только локально
        deny all;
    }
}

Затем запустите экспортер (пример для Docker Compose):

yamlКопировать
services:
  nginx-exporter:
    image: nginx/nginx-prometheus-exporter:latest
    ports:
      - "9113:9113"
    command:
      - '-nginx.scrape-uri=http://localhost:8080/metrics'

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

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

Однако стоит учитывать два момента:

1. Частота опроса (scrape interval). Если вы поставите интервал в 1 секунду, то при большом количестве запросов к самому endpoint /metrics вы создадите лишнюю нагрузку на сетевой стек. 15–30 секунд — золотая середина для большинства задач.
2. Объём данных. Если вы используете расширенные модули (например, для сбора метрик каждого отдельного виртуального хоста), объем передаваемых данных растёт.

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

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

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

Как понять, что Nginx действительно отдает метрики?

Для проверки работоспособности выполните запрос к эндпоинту, который вы указали в конфигурации stub_status. Если вы видите текстовый вывод со статистикой соединений и запросов, значит, модуль работает корректно. Если же вы получаете ошибку 404 или 403, проверьте права доступа в блоке location и убедитесь, что Nginx был перезагружен после внесения изменений в конфиг.

Влияет ли включение модуля stub_status на производительность сервера?

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

Можно ли собирать метрики, если я использую Nginx в Docker?

Да, это стандартная задача, но здесь важно правильно пробросить порты. Если вы вынесли эндпоинт со статистикой на отдельный порт, убедитесь, что этот порт опубликован в конфигурации контейнера. В конфигурации Prometheus в качестве цели (target) нужно будет указывать IP-адрес хоста или имя сервиса, если Prometheus и Nginx находятся в одной Docker-сети.

Чем нативный метод лучше использования nginx-prometheus-exporter?

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