Продвинутый

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

Алексей Кузнецов
Алексей Кузнецов
Системный администратор28 октября 2026 г.15 мин чтения

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

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

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

Зачем Nginx нужен нативный сбор метрик

Зачем Nginx нужен нативный сбор метрик

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

Проблема сторонних экспортеров

Традиционный подход подразумевает связку: Nginx (stub_status) $\rightarrow$ Nginx Exporter $\rightarrow$ Prometheus. С точки зрения архитектуры это создаёт лишнее звено. Если мы посмотрим на эту схему, то увидим потенциальные точки отказа:

  1. Дополнительный расход ресурсов. Даже если экспортер написан на Go и потребляет мало, в масштабах кластера из десятков нод это лишние процессы, которые нужно мониторить, обновлять и защищать.
  2. Несоответствие данных. Сторонние инструменты парсят текстовый вывод модуля stub_status. Если в новой версии Nginx формат вывода изменится (что случается редко, но всё же), экспортер может начать отдавать некорректные значения или вовсе перестать работать.
  3. Сложность отладки. Когда в Grafana вы видите просадку по количеству запросов, вам приходится выяснять: это реально упал трафик, или экспортер не смог достучаться до локального сокета Nginx?

Для тех, кто привык строить предсказуемые системы, такая неопределённость — лишний шум. Если вы уже настраивали дашборды для домашней лаборатории, то знаете, что чистота данных важнее их количества.

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

Нативная поддержка метрик (через модуль nginx-module-vts или встроенные возможности в коммерческих версиях, а также через современные подходы в Open Source) позволяет Prometheus забирать данные напрямую.

С практической точки зрения, переход на прямой сбор даёт три ключевых преимущества:

  • Предсказуемость. Метрики поступают из первоисточника. Нет промежуточного слоя, который может исказить цифры или отвалиться по собственной инициативе.
  • Минимизация конфигурации. Вам не нужно управлять отдельным сервисом. Всё настраивается внутри основного конфига Nginx. Если работает Nginx — работают и метрики.
  • Снижение нагрузки на систему. Мы убираем лишние сетевые запросы и процессы парсинга.

Для примера, вместо того чтобы запускать отдельный контейнер с экспортером, мы можем просто настроить секцию в nginx.conf, которая будет отдавать данные в формате, понятном Prometheus.

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

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

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

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

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

bash
nginx -V 2>&1 | grep --color http_stub_status_module

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

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

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

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

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

nginx
server {
    listen 80;
    server_name localhost;

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

    # Секция для метрик
    location /metrics {
        stub_status;
        
        # Ограничиваем доступ только для локального хоста или IP вашего Prometheus
        allow 127.0.0.1;
        allow 192.168.1.50; # IP вашего сервера мониторинга
        deny all;
    }
}

Обратите внимание на директиву stub_status;. Она не требует параметров и просто активирует отдачу текстовых данных в формате, который мы увидим при обращении к /metrics. После внесения изменений обязательно проверьте синтаксис:

bash
sudo nginx -t

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

bash
sudo systemctl reload nginx

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

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

Если в Nginx вы указали location /metrics, то в конфиге Prometheus это должно выглядеть так:

yaml
scrape_configs:
  - job_name: 'nginx_status'
    static_configs:
      - targets: ['192.168.1.10:80']
    metrics_path: '/metrics'

Если вы забудете указать metrics_path, Prometheus по умолчанию будет искать данные по адресу /metrics. В данном случае это совпадает, но если вы решите назвать эндпоинт иначе, например, /status, то без явного указания пути в конфиге вы получите ошибку 404 Not Found в логах сборщика.

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

Сбор данных через Prometheus

Сбор данных через Prometheus

Когда мы говорим о мониторинге, предсказуемость — это первое, на что я смотрю. Использование сторонних экспортеров, которые работают через парсинг stub_status, добавляет лишнее звено в цепочку: если экспортер упадет или изменится формат вывода, вы останетесь без метрик, даже если сам Nginx работает исправно. Нативная поддержка позволяет получать данные напрямую, что делает систему более устойчивой.

Настройка scrape_configs в prometheus.yml

Чтобы Prometheus начал забирать метрики, нужно описать задачу (job) в его конфигурационном файле. Здесь важно не просто указать адрес, но и правильно настроить интервалы, чтобы не создавать избыточную нагрузку на веб-сервер, особенно если у вас много виртуальных хостов.

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

yaml
scrape_configs:
  - job_name: 'nginx-native'
    # Интервал сбора данных. 15 секунд — золотая середина для большинства задач.
    scrape_interval: 15s
    # Время ожидания ответа от сервера.
    scrape_timeout: 10s
    static_configs:
      - targets: ['localhost:8080'] # Укажите IP и порт, на котором Nginx отдает метрики

Обратите внимание на параметр targets. Если ваш Nginx работает в Docker-контейнере, вместо localhost нужно использовать имя сервиса или IP-адрес контейнера в вашей сети. Если вы строите дашборд для домашней лаборатории с помощью Dashy, убедитесь, что Prometheus имеет сетевой доступ к эндпоинту Nginx.

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

После того как вы сохранили конфигурацию и перезапустили Prometheus (или выполнили curl -X POST http://localhost:9090/-/reload), нужно убедиться, что данные действительно поступают.

Сначала проверьте, доступен ли эндпоинт метрик с самой машины, где запущен Nginx. Используйте curl, чтобы увидеть «сырой» вывод в формате Prometheus:

bash
curl -v http://localhost:8080/metrics

В ответе вы должны увидеть список метрик, начинающихся с префикса nginx_. Например:

  • nginx_up — статус доступности сервиса;
  • nginx_connections_active — количество активных соединений.

Если вы получили ошибку 403 Forbidden или 404 Not Found, значит, проблема в конфигурации location внутри Nginx. Проверьте, что доступ к эндпоинту разрешен для IP-адреса, с которого Prometheus делает запросы.

Если вы используете Nginx как прокси-сервер, убедитесь, что правила доступа не блокируют внутренние запросы. Это часто случается, когда администраторы настраивают строгие правила в секции allow / deny, забывая про подсеть мониторинга. Если метрики не отдаются, проверьте логи ошибок: tail -f /var/log/nginx/error.log.

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

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

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

На Grafana Labs есть множество сообществ, которые делятся своими наработками. Для нашей задачи — когда мы используем нативный модуль Nginx, а не сторонний экспортер — важно искать дашборды, которые ориентированы именно на nginx_exporter или напрямую на метрики, отдаваемые модулем.

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

Для работы с Nginx я обычно выбираю дашборды с ID 12708 или аналогичные. При импорте в Grafana вам нужно будет указать ваш Prometheus как источник данных (Data Source).

С практической точки зрения, хороший дашборд для Nginx должен содержать три уровня детализации:

  1. Общий статус: количество активных соединений (active connections) и общее число запросов в секунду (RPS).
  2. Производительность: распределение ответов по кодам состояния (2xx, 3xx, 4xx, 5xx). Это критически важно для быстрого понимания, что происходит: сервер работает или «сыплет» ошибками.
  3. Ресурсы: задержки (latency) и время обработки запросов.

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

Настройка алертов по ключевым показателям

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

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

С точки зрения надежности, я выделяю два типа алертов для Nginx:

1. Критические (Critical) Это события, требующие немедленного вмешательства. Например, резкий рост 5xx ошибок. Если процент ошибок превышает порог (допустим, 5% от общего трафика) в течение последних 2–5 минут, это сигнал о проблеме в приложении или конфигурации.

Пример правила для alerting_rules.yml:

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

2. Предупреждающие (Warning) Это сигналы о том, что система начинает выходить за рамки нормы, но прямо сейчас всё работает. Например, постепенный рост количества активных соединений, который может укачь на утечку ресурсов или медленную работу бэкенда.

Для настройки таких правил используйте более длинные интервалы for (например, 10–15 минут), чтобы избежать ложных срабатываний из-за кратковременных всплесков трафика.

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

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

Заключение

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

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

С практической точки зрения, я рекомендую внедрять этот метод поэтапно:

  1. Сначала настройте сбор базовых метрик (количество запросов, размер тела ответа, ошибки 4xx/5xx).
  2. Проверьте, как Prometheus подхватывает эти данные, используя scrape_configs в prometheus.yml.
  3. Только после подтверждения корректности данных настраивайте сложные дашборды.

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

Когда нативный метод может не подойти

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

Основные сценарии, когда стоит вернуться к экспортерам:

  • Вам нужна детализация по конкретным User-Agent.
  • Вы хотите анализировать паттерны поведения пользователей, а не только нагрузку на сервер.
  • Вы используете сборку Nginx, которую невозможно пересобрать с нужным модулем.

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

Чек-лист проверки конфигурации

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

  1. Проверка синтаксиса: Всегда запускайте проверку конфига перед перезагрузкой.
    bash
    nginx -t
    
  2. Доступность эндпоинта: Проверьте, что метрики отдаются именно в том формате, который ожидает Prometheus.
    bash
    curl -s http://localhost/metrics | grep nginx_
    
  3. Безопасность: Убедитесь, что эндпоинт с метриками не доступен из внешнего интернета. Он должен быть закрыт либо через allow/deny в конфиге Nginx, либо через настройки сетевого экрана.

Пример правильной секции ограничения доступа в nginx.conf:

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

    stub_status; # Или конфигурация вашего модуля метрик
}

Если вы настроили всё верно, Prometheus будет стабильно забирать данные, а вы сможете вовремя заметить аномалии в трафике до того, как они превратятся в инцидент.

FAQ

Как исправить ошибку в URL метрик Nginx?

Чаще всего проблема заключается в неверном пути в конфигурации scrape_configs внутри prometheus.yml. Если вы настроили модуль stub_status на определённом location, Prometheus должен обращаться именно по этому адресу.

Если в конфиге Nginx вы указали:

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

То в настройках Prometheus секция static_configs должна содержать правильный targets и metrics_path. Если путь в Nginx отличается от стандартного /metrics, обязательно укажите его явно:

yaml
scrape_configs:
  - job_name: 'nginx_native'
    metrics_path: '/metrics' # Убедитесь, что этот путь совпадает с location в Nginx
    static_configs:
      - targets: ['localhost:80']

Также проверьте, не блокирует ли ваш firewall или правила allow/deny в самом Nginx запросы от сервера мониторинга.

Нужен ли nginx-exporter при наличии нативной поддержки?

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

Однако nginx-exporter собирает гораздо больше данных: детализацию по статус-кодам (4xx, 5xx), распределение по методам (GET, POST) и работу конкретных upstream-серверов.

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

Какие метрики доступны через stub_status?

Модуль stub_status выдаёт ограниченный, но критически важный набор данных. При обращении к эндпоинту вы увидите следующие показатели:

  • Active connections: количество текущих соединений.
  • Accepts: общее число принятых соединений.
  • Handled: количество обработанных соединений.
  • Requests: общее количество запросов.
  • Reading: количество соединений, на которых Nginx читает заголовки.
  • Writing: количество соединений, на которых Nginx пишет ответ клиенту.
  • Waiting: количество свободных (keep-alive) соединений.

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

Как проверить, что Prometheus видит метрики?

Самый быстрый способ — проверить доступность эндпоинта вручную с помощью curl. Выполните команду на сервере, где запущен Nginx:

bash
curl http://localhost/metrics

Вы должны получить текстовый ответ в формате Active connections: 2 .... Если команда возвращает ошибку 403 или 404, проблема в конфигурации Nginx.

Если с curl всё в порядке, переходите в веб-интерфейс Prometheus. В меню выберите Status — Targets. Найдите ваш job (например, nginx_native). Если состояние (State) указано как UP, значит, Prometheus успешно забирает данные. Если статус DOWN, внимательно изучите колонку Error — там будет указана причина, будь то ошибка тайм-аута или неверный URL.

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

Чем нативный сбор метрик отличается от использования Nginx Exporter?

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

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

Если вы используете стандартную сборку Nginx, вам потребуется модуль http_stub_status_module. В большинстве современных дистрибутивов Linux он уже включён в состав пакета, но проверить это можно командой nginx -V. Если же вам нужны расширенные метрики (например, по конкретным upstream-серверам), придётся собрать Nginx из исходников с модулем nginx-module-vts.

Как ограничить доступ к эндпоинту с метриками?

Эндпоинт с метриками не должен быть доступен из публичного интернета, так как он раскрывает детали работы вашей инфраструктуры. С практической точки зрения лучше всего ограничить доступ на уровне location в конфигурационном файле, разрешив запросы только с IP-адреса вашего сервера Prometheus. Это можно сделать с помощью директив allow и deny.

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

Сбор метрик через встроенные модули создаёт минимальную нагрузку на CPU и память, сопоставимую с обработкой обычного HTTP-запроса. Однако при очень высокой интенсивности запросов стоит следить за тем, как часто Prometheus опрашивает эндпоинт. Если интервал сбора (scrape interval) слишком короткий, это может создать избыточную нагрузку на сетевой стек и логирование.

Можно ли собирать метрики, если Nginx работает в Docker-контейнере?

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

Поделиться:TelegramX / TwitterVK

Читайте также