Интеграция Nginx с Prometheus: нативная настройка

Интеграция Nginx с Prometheus: нативная настройка

Разбираем способ подключения Nginx к Prometheus для сбора метрик без сторонних модулей. Настройка экспорта данных и исправление ошибок в конфигурации URL.

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

Проблема сбора метрик

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

Основная сложность заключается в том, что Nginx по умолчанию не отдает метрики в формате, который понимает Prometheus. Если вы просто посмотрите access.log, вы увидите поток событий: кто зашёл, какой URL запросил и какой статус получил. Но из логов крайне тяжело вычленить общую картину. Например, вы не сможете мгновенно увидеть график роста количества 5xx ошибок или понять, не упёрлись ли вы в лимит дескрипторов файлов.

Раньше для решения этой задачи все использовали сторонний модуль nginx-module-vts или запускали отдельный процесс-экспортер, который парсил логи. С практической точки зрения это создаёт лишнюю нагрузку на систему и усложняет конфигурацию: вам нужно следить за работоспособностью самого экспортера, обновлять его и следить, чтобы он не «съел» все ресурсы, предназначенные для полезной нагрузки. В масштабах домашнего сервера, где ресурсы ограничены, лишний процесс — это всегда компромисс.

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

Нативная интеграция позволяет получать данные напрямую из процесса Nginx. Это даёт ту самую предсказуемость, к которой я стремлюсь при настройке любой инфраструктуры. Вместо того чтобы строить цепочку «Nginx $\to$ Log Parser $\to$ Prometheus», мы получаем прямую связь.

Если мы посмотрим на преимущества такого подхода, можно выделить три ключевых момента:

1. Минимальный оверхед. Мы не запускаем дополнительный сервис, который постоянно читает диск и парсит текстовые файлы. Данные собираются «на лету» из памяти процесса.
2. Точность данных. Метрики, которые отдает сам Nginx, отражают реальное состояние воркеров и соединений, а не то, что успел записать логгер.
3. Простота поддержки. Конфигурация становится прозрачной. Если Nginx работает, то и метрики работают.

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

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

Настройка модуля stub_status

Настройка модуля stub_status

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

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

Конфигурация секции server

Чтобы не открывать статистику всему интернету, я рекомендую выносить эндпоинт с метриками в отдельный блок location. Лучше всего ограничить доступ к нему по IP-адресу того сервера, где запущен Prometheus, или хотя бы через внутреннюю сеть.

Если вы настраиваете домашнюю лабораторию, убедитесь, что этот порт или путь не проброшен наружу в ваш роутер.

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

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

    # Основной трафик
    location / {
        root /var/www/html;
        index index.html;
    }

    # Эндпоинт для сбора метрик
    location /metrics {
        stub_status on; # Включаем модуль
        
        # Ограничиваем доступ только для Prometheus
        # Замените 192.168.1.50 на IP вашего сервера мониторинга
        allow 192.168.1.50;
        deny all;
    }
}

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

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

Если ошибок нет, примените настройки:

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

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

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

Прежде чем прописывать путь в prometheus.yml, нужно убедиться, что Nginx действительно отдает данные в нужном формате. Для этого можно использовать curl.

Если вы всё настроили правильно и запускаете команду с разрешённого IP, вы увидите нечто подобное:

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

Ожидаемый вывод:

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

Здесь:

• Active connections — текущее число активных соединений.
• accepts — общее количество принятых соединений.
• handled — количество обработанных соединений.
• requests — общее количество запросов.

Если вы получаете ошибку 403 Forbidden, значит, правило allow/deny работает слишком строго или вы обращаетесь не с того адреса. Если 404 Not Found — проверьте, правильно ли указан путь в блоке location и применили ли вы конфигурацию через systemctl reload.

Важно понимать: stub_status выдаёт данные в текстовом виде, а не в формате Prometheus. Чтобы Prometheus «понял» их, нам понадобится небольшой посредник — nginx-prometheus-exporter. О том, как его настроить, мы поговорим в следующем разделе.

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

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

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

Важно понимать, что Prometheus работает по модели pull: он сам обращается к целевым объектам (таргетам) и запрашивает данные. Если в конфигурации допустить ошибку, вы получите пустые графики в Grafana или, что хуже, постоянные алерты о состоянии «Down».

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

Для добавления Nginx в список мониторинга нужно отредактировать секцию scrape_configs. Я рекомендую выделять каждый сервис в отдельный job. Это обеспечит предсказуемость: если один сервис перестанет отвечать, вы сразу увидите это в интерфейсе Prometheus, и это не смешается с метриками других систем.

Допустим, ваш Nginx слушает метрики на порту 9113 (стандарт для nginx-exporter) или на отдельном порту, который вы настроили в конфиге самого веб-сервера. Пример настройки в prometheus.yml будет выглядеть так:

yamlКопировать
scrape_configs:
  # Настройка для сбора метрик с Nginx
  - job_name: 'nginx_metrics'
    # Интервал, с которым Prometheus будет опрашивать сервер
    scrape_interval: 15s
    # Время, по истечении которого таргет будет считаться недоступным
    scrape_timeout: 10s
    static_configs:
      - targets: ['192.168.1.50:9113'] # IP вашего сервера Nginx и порт

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

Исправление ошибок в URL таргетов

Частая ошибка, с которой я сталкивался при аудите инфраструктуры, — неправильное указание пути (path) к метрикам. По умолчанию Prometheus ожидает, что метрики доступны по адресу /metrics. Однако, если вы настраивали Nginx так, чтобы отдавать данные по специфическому пути (например, /status/metrics), Prometheus просто не найдёт нужную страницу.

Если путь отличается от стандартного, его необходимо явно указать в секции metrics_path.

Пример конфигурации с кастомным путем:

yamlКопировать
  - job_name: 'nginx_custom_path'
    metrics_path: '/status/metrics' # Указываем путь, если он не /metrics
    static_configs:
      - targets: ['nginx-server:80']

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

nginxКопировать
location /status/metrics {
    allow 192.168.1.10; # IP сервера с Prometheus
    deny all;
    stub_status; # Или другой модуль для отдачи метрик
}

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

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

bashКопировать
# Если Prometheus запущен как системная служба
sudo systemctl reload prometheus

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

Визуализация метрик в Grafana

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

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

Для начала я рекомендую зайти на Grafana Labs Dashboards и поискать готовые решения по запросу «Nginx». Если вы используете стандартный Nginx VTS (Virtual Host Traffic Status) или экспортер, вам подойдут шаблоны с ID вроде 12708 или 14900.

При выборе дашборда ориентируйтесь на три уровня детализации:

1. Общий уровень (High-level): количество запросов в секунду (RPS), текущее число активных соединений и процент ошибок (4xx и 5xx). Это то, на что вы посмотрите в первую очередь, если что-то пошло не так.
2. Уровень ресурсов: нагрузка на CPU и память процессами Nginx. Это помогает понять, не упёрлись ли вы в аппаратные ограничения вашего сервера.
3. Уровень соединений: распределение по типам (waiting, reading, writing) и использование Keep-Alive.

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

Настройка алертов по нагрузке

Визуализация полезна, когда вы сидите перед монитором, но настоящая предсказуемость системы появляется тогда, когда она сама сообщает о проблемах. В Prometheus для этого используется Alertmanager.

Я не сторонник «шумных» алертов, которые срабатывают на каждое кратковременное колебание. Если настроить уведомление на разовый скачок 5xx ошибок, вы быстро перестанете обращать на них внимание. Правильный подход — использовать функцию for в правилах Prometheus, чтобы подтверждать устойчивость аномалии.

Пример правила для обнаружения всплеска ошибок в Nginx:

yamlКопировать
groups:
- name: nginx_alerts
  rules:
  - alert: NginxHighErrorRate
    # Считаем процент 5xx ошибок от общего числа запросов
    expr: |
      sum(rate(nginx_http_requests_total{status=~"5.."}[5m])) 
      / 
      sum(rate(nginx_http_requests_total[5m])) > 0.05
    # Алерту должно быть не менее 2 минут, чтобы исключить случайные всплески
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "Высокий уровень ошибок на Nginx"
      description: "Доля 5xx ошибок превысила 5% за последние 5 минут на хосте {{ $labels.instance }}"

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

Для настройки уведомлений (в Telegram, Slack или на почту) после срабатывания правила, вам потребуется сконфигурировать alertmanager.yml. Убедитесь, что в секции receivers указаны верные параметры доступа к вашему мессенджеру, иначе сигнал о падении сервиса просто уйдет в пустоту.

Заключение

Итоги настройки

Если мы подведём итог, то нативная интеграция Nginx с Prometheus — это прежде всего предсказуемость. Вам не нужно внедрять сторонние модули, которые могут конфликтовать с основной логикой обработки трафика или требовать пересборки бинарного файла. Мы настроили экспорт метрик через стандартный stub_status, что даёт необходимый минимум: количество активных соединений, обработанных запросов и состояние рабочих процессов.

С практической точки зрения, такая конфигурация идеальна для мониторинга состояния самого веб-сервера. Однако важно понимать ограничения: нативный модуль не отдаёт детальную статистику по конкретным URL-адресам или HTTP-кодам ответа (4xx, 5xx). Для глубокого анализа трафика всё же придётся использовать Nginx VTS exporter, но для базового контроля «жив ли сервер и не забит ли пул соединений» текущего решения более чем достаточно.

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

Существует несколько сценариев, когда текущая схема потребует пересмотра:

1. Рост нагрузки на мониторинг. Если вы решите опрашивать stub_status слишком часто (например, раз в секунду), это создаст лишнюю нагрузку на процесс Nginx. Оптимальный интервал для Prometheus — от 15 до 30 секунд.
2. Необходимость сегментации. Если у вас на одном экземпляре Nginx крутится десяток разных сайтов, общие метрики сервера не дадут понимания, какой именно домен потребляет ресурсы. В этом случае лучше выносить критические сервисы на отдельные инстансы или использовать более продвинутые экспортеры.
3. Сложные требования к безопасности. Не забудьте, что эндпоинт /metrics (или тот, что вы указали в location) должен быть закрыт от внешнего мира.

Чтобы обезопасить доступ к метрикам, я всегда ограничиваю их только локальным интерфейсом или конкретным IP-адресом сервера мониторинга. Пример правильной настройки в nginx.conf:

nginxКопировать
location /metrics {
    stub_status;
    # Разрешаем доступ только локальному хосту и серверу Prometheus
    allow 127.0.0.1;
    allow 192.168.1.50; 
    deny all;
}

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

FAQ

Как Prometheus забирает метрики из Nginx

Prometheus работает по модели pull: он сам обращается к эндпоинту, который вы указали в конфигурации scrape_configs. Чтобы это работало, Nginx должен отдавать данные в текстовом формате, который понимает Prometheus.

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

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

    location /metrics {
        stub_status on;
        allow 127.0.0.1; # Разрешаем доступ только локальному агенту
        deny all;        # Запрещаем всем остальным
    }
}

После настройки проверьте доступность через curl:

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

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

Почему Prometheus выдаёт ошибку "Connection Refused"

Чаще всего проблема кроется в одной из трёх причин:

1. Nginx слушает не тот интерфейс. Если в конфиге указано listen 127.0.0.1:8080, а Prometheus запущен в Docker-контейнере, он не сможет достучаться до хоста по этому адресу. В таком случае нужно либо слушать на всех интерфейсах (0.0.0.0), либо настраивать сетевой мост.
2. Неправильный порт. Проверьте, что порт в prometheus.yml совпадает с тем, что прописан в listen внутри Nginx.
3. Firewall. Если сбор метрик идёт с другого сервера, убедитесь, что порт открыт в iptables или nftables.

Для проверки того, какой порт сейчас слушает Nginx, используйте команду:

bashКопировать
ss -tlnp | grep nginx

Как защитить эндпоинт со статистикой

Выставлять /metrics в открытый интернет — плохая идея. Это не только вопрос безопасности, но и лишняя нагрузка на сервер. Предсказуемость системы важнее, чем удобство быстрого доступа.

Лучший способ — ограничить доступ на уровне конфигурации Nginx, разрешив запросы только с IP-адреса вашего сервера мониторинга.

nginxКопировать
location /metrics {
    stub_status on;
    allow 192.168.1.50; # IP вашего сервера Prometheus
    deny all;
}

Если вы используете контейнеризацию, вместо конкретного IP лучше использовать внутреннюю сеть Docker. Помните, что безопасность инфраструктуры — это комплексный процесс, и даже такие мелочи, как закрытый эндпоинт метрик, важны для общей устойчивости. Если вас интересуют более глубокие вопросы защиты, посмотрите наш анализ уязвимости Canvas API.

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

Стандартный stub_status даёт лишь базовую информацию: количество активных соединений, принятых и обработанных запросов. Для глубокого анализа (например, распределения ответов по кодам состояния 2xx, 4xx, 5xx) нативного модуля недостаточно.

В таких случаях инженеры обычно используют nginx-vts-exporter или специализированные сборщики. Однако, если ваша задача — просто следить за тем, не «лежит» ли сервер и не растёт ли число соединений до критического уровня, стандартного модуля будет вполне достаточно. Это позволяет сохранить конфигурацию чистой и не усложнять систему лишними зависимостями.

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

Нужно ли устанавливать дополнительный экспортер для сбора метрик

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

Как обеспечить безопасность эндпоинта с метриками

Эндпоинт, через который Prometheus забирает данные, нельзя оставлять открытым для всего интернета. Рекомендую ограничить доступ к этому URL с помощью директивы allow и deny в блоке location, разрешив запросы только с IP-адреса вашего сервера мониторинга. Если Prometheus работает в другом контейнере, используйте внутреннюю подсеть Docker или IP-адрес шлюза.

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

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

Что делать, если Prometheus не видит метрики после настройки

Сначала проверьте доступность эндпоинта локально, выполнив запрос curl прямо с сервера, где запущен Nginx. Если вы получаете корректный текст в формате Prometheus, значит, проблема в конфигурации prometheus.yml или в сетевых правилах (firewall). Если же curl возвращает ошибку, проверьте логи Nginx и убедитесь, что секция location прописана внутри нужного блока server.