Nginx Status Module: настройка мониторинга производительности сервера

Nginx Status Module (ngx_http_stub_status_module) - встроенный инструмент для получения базовых метрик производительности веб-сервера. Модуль показывает активные соединения, общее количество принятых и обработанных запросов, а также состояния чтения, записи и ожидания. Это фундамент для мониторинга без сторонних плагинов или агентов.

Мониторинг Nginx критически важен для выявления узких мест, обнаружения аномалий в трафике и планирования мощностей. Без метрик вы работаете вслепую: не знаете, когда сервер приближается к пределу worker_connections, растёт ли очередь запросов или увеличивается доля ошибок. Stub_status даёт минимально необходимый набор данных, который закрывает 80% потребностей в наблюдаемости.

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

Что такое Nginx Status Module и зачем он нужен

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

Эти метрики помогают ответить на конкретные вопросы администратора:

Сколько клиентов подключено к серверу прямо сейчас?
Растёт ли нагрузка со временем?
Есть ли соединения, которые сервер принял, но не смог обработать?
Эффективно ли используются keep-alive соединения?

Без модуля вы вынуждены анализировать логи доступа или полагаться на системные утилиты вроде netstat, которые не дают картины на уровне приложения. Stub_status встроен в Nginx и работает с минимальными накладными расходами - сбор метрик не влияет на производительность обработки запросов.

Для полной картины мониторинга рекомендуем также изучить готовые конфигурации Prometheus и Grafana для мониторинга Nginx с алертингом на ошибки 502/504.

Шаг 1: Проверка и включение модуля ngx_http_stub_status_module

Перед настройкой эндпоинта убедитесь, что модуль присутствует в вашей сборке Nginx. Если модуль отсутствует, потребуется переустановка пакета или пересборка из исходников.

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

Выполните команду, которая выводит параметры компиляции Nginx и фильтрует строку с именем модуля:

nginx -V 2>&1 | grep --color -o with-http_stub_status_module

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

Пример вывода при наличии модуля:

--with-http_stub_status_module

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

nginx -V 2>&1

Установка Nginx с поддержкой stub_status

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

Ubuntu/Debian: стандартный пакет nginx может не включать модуль. Установите расширенную версию:

apt update
apt install nginx-full

Пакет nginx-extras также содержит модуль и включает дополнительные возможности, такие как встроенный Perl и сторонние модули.

CentOS/RHEL: модуль включён в стандартный пакет из репозитория EPEL. Установка:

yum install nginx

Сборка из исходников: добавьте флаг при конфигурации:

./configure --with-http_stub_status_module [другие флаги]
make
make install

Docker: официальный образ nginx:latest включает модуль. Проверьте командой внутри контейнера:

docker run --rm nginx:latest nginx -V 2>&1 | grep stub_status

Если вы используете минималистичный образ, соберите свой Dockerfile на базе официального:

FROM nginx:latest
# Модуль уже встроен, дополнительных действий не требуется

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

nginx -t && systemctl restart nginx

Шаг 2: Настройка защищённого эндпоинта для статусной страницы

Эндпоинт со статусом раскрывает информацию о нагрузке на сервер. Открытый доступ позволяет злоумышленнику оценить мощность инфраструктуры, обнаружить пики нагрузки и выбрать момент для атаки. Настройте минимум один уровень защиты - по IP-адресам или базовой HTTP-аутентификации. Рекомендуем комбинировать оба метода.

Базовая конфигурация location со stub_status

Минимальная конфигурация в серверном блоке:

server {
    listen 8080;
    server_name localhost;

    location /nginx_status {
        stub_status;
    }
}

Эта конфигурация открывает метрики всем, кто может обратиться к порту 8080. Используйте её только для тестирования в изолированной среде. В production немедленно добавьте ограничения.

Ограничение доступа по IP-адресам

Разрешите доступ только с доверенных адресов - серверов мониторинга, внутренней сети или VPN:

location /nginx_status {
    stub_status;
    allow 192.168.1.0/24;
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    deny all;
}

Директивы обрабатываются последовательно: сначала проверяются разрешающие правила, затем запрещающее deny all блокирует всех остальных. Укажите конкретные IP-адреса ваших серверов Prometheus или экспортера вместо целых подсетей для более строгого контроля.

Добавление базовой HTTP-аутентификации

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

Создайте файл паролей утилитой htpasswd:

htpasswd -c /etc/nginx/.htpasswd monitor_user

Утилита запросит пароль и создаст файл с хешем. Ключ -c используется только при первом создании файла - при повторном использовании он перезапишет существующих пользователей. Для добавления новых пользователей опустите этот ключ:

htpasswd /etc/nginx/.htpasswd another_user

Добавьте директивы аутентификации в location:

location /nginx_status {
    stub_status;
    allow 192.168.1.100;
    allow 10.0.0.50;
    deny all;
    auth_basic "Nginx Status";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Строка «Nginx Status» - это сообщение, которое увидит пользователь в диалоге ввода пароля. Укажите что-то информативное, но не раскрывающее внутренние детали.

Проверьте синтаксис конфигурации и перезагрузите Nginx:

nginx -t && systemctl reload nginx

Протестируйте доступ с разрешённого IP:

curl -u monitor_user:password http://192.168.1.100:8080/nginx_status

И с запрещённого - должны получить 403 Forbidden.

Шаг 3: Интерпретация метрик - что означают цифры

После настройки эндпоинта вы увидите страницу с данными в таком формате:

Active connections: 2
server accepts handled requests
 15234 15234 28901
Reading: 0 Writing: 1 Waiting: 1

Каждая строка содержит конкретную информацию о состоянии сервера. Разберём все поля детально.

Active connections и состояния Reading, Writing, Waiting

Active connections - общее количество открытых клиентских соединений в данный момент. В это число входят соединения, которые активно читают или пишут данные, а также ожидающие keep-alive соединения.

Три состояния соединений:

Reading - Nginx читает заголовок запроса от клиента. Высокое значение указывает на медленных клиентов, отправляющих данные слишком долго, или на большое количество входящих соединений.
Writing - Nginx читает тело запроса от клиента или отправляет ответ. Рост этого показателя сигнализирует о медленных бэкендах, которые долго формируют ответ, или о клиентах с плохим каналом.
Waiting - keep-alive соединения, которые остаются открытыми после завершения запроса в ожидании следующего. Высокое значение - норма для сайтов с keep-alive. Это не проблема, пока количество не превышает лимит worker_connections.

Тревожный сигнал: сумма Reading и Writing постоянно высокая при небольшом количестве Waiting. Это означает, что соединения «застревают» в активных состояниях - вероятно, проблема с бэкендом или клиентской сетью.

Счётчики accepts, handled, requests

Вторая строка содержит накопительные счётчики с момента запуска Nginx:

accepts - общее количество принятых клиентских соединений.
handled - количество соединений, которые были успешно обработаны. Разница между accepts и handled показывает число соединений, принятых, но не обработанных - обычно из-за исчерпания лимита worker_connections.
requests - общее количество обработанных запросов. Один клиент по keep-alive соединению может отправить несколько запросов, поэтому requests часто больше accepts.

Как использовать эти счётчики для расчёта RPS (запросов в секунду):

Запишите значение requests в момент T1.
Через 60 секунд запишите значение в момент T2.
RPS = (requests_T2 - requests_T1) / 60.

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

Для более глубокого анализа логов и настройки алертинга используйте готовые скрипты анализа логов Nginx.

Шаг 4: Интеграция с Prometheus и Grafana

Stub_status отдаёт метрики в текстовом формате, который Prometheus не понимает. Для преобразования нужен экспортер - промежуточный сервис, который забирает данные с эндпоинта Nginx и отдаёт их в формате, совместимом с Prometheus.

Установка и запуск nginx-prometheus-exporter

Официальный экспортер от Nginx доступен на GitHub и в виде Docker-образа. Запуск через Docker - самый простой способ:

docker run -d \
  --name nginx-exporter \
  -p 9113:9113 \
  nginx/nginx-prometheus-exporter:latest \
  -nginx.scrape-uri=http://192.168.1.100:8080/nginx_status

Флаг -nginx.scrape-uri указывает URL вашего защищённого эндпоинта. Если настроена базовая аутентификация, добавьте учётные данные в URL:

-nginx.scrape-uri=http://monitor_user:password@192.168.1.100:8080/nginx_status

Проверьте, что экспортер отдаёт метрики:

curl http://localhost:9113/metrics

Вы увидите метрики в формате Prometheus: nginx_connections_active, nginx_http_requests_total и другие.

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

Добавьте новый job в секцию scrape_configs файла prometheus.yml:

scrape_configs:
  - job_name: 'nginx'
    scrape_interval: 15s
    static_configs:
      - targets: ['192.168.1.50:9113']
        labels:
          environment: 'production'

Перезагрузите Prometheus:

curl -X POST http://localhost:9090/-/reload

Проверьте, что target появился в веб-интерфейсе Prometheus по адресу http://localhost:9090/targets. Состояние должно быть «UP».

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

Самый быстрый способ - импортировать готовый дашборд. В Grafana перейдите в Dashboards → Import и введите ID 11199 (популярный дашборд для Nginx). Укажите источник данных Prometheus и нажмите Import.

Для создания собственного дашборда добавьте базовые панели:

Активные соединения: nginx_connections_active - линейный график, показывает текущую нагрузку.
Запросы в секунду: rate(nginx_http_requests_total[1m]) - скорость поступления запросов.
Соединения в ожидании: nginx_connections_waiting - мониторинг keep-alive соединений.
Соотношение accepts/handled: rate(nginx_connections_accepted[1m]) - rate(nginx_connections_handled[1m]) - отброшенные соединения.

Настройте алерты в Grafana на критические метрики: резкое падение handled относительно accepts или превышение порога активных соединений над 80% от worker_connections.

Для комплексного подхода к мониторингу Nginx изучите руководство по мониторингу upstream и health checks с готовыми конфигурациями для Prometheus и Grafana.

Диагностика и решение типичных проблем

При настройке stub_status администраторы сталкиваются с несколькими типовыми ошибками. Вот решения для каждой из них.

Ошибка «unknown directive stub_status»

Nginx не распознаёт директиву stub_status в конфигурации. При перезапуске или проверке синтаксиса выводится:

nginx: [emerg] unknown directive "stub_status"

Причина: модуль ngx_http_stub_status_module не собран с вашим экземпляром Nginx.

Решение: проверьте наличие модуля командой nginx -V 2>&1 | grep stub_status. Если модуль отсутствует, переустановите пакет (nginx-full на Debian/Ubuntu) или пересоберите Nginx из исходников с флагом --with-http_stub_status_module. После установки проверьте, что вы запускаете именно новый бинарный файл, а не старый.

Проблемы с доступом: 403 и 404

Ошибка 403 Forbidden: доступ заблокирован директивами allow/deny.

Проверьте порядок директив: deny all должно быть последним.
Убедитесь, что IP-адрес клиента совпадает с указанным в allow. Если Nginx стоит за прокси или балансировщиком, он видит IP прокси, а не клиента. Используйте директиву set_real_ip_from и real_ip_header для проброса реального IP.
Временно закомментируйте allow/deny для изоляции проблемы.

Ошибка 404 Not Found: location не совпадает с запросом.

Проверьте, что location определён в правильном server block - том, который слушает порт, к которому вы обращаетесь.
Убедитесь, что нет конфликтующих location с регулярными выражениями, которые перехватывают запрос раньше.
Проверьте listen директиву: если указан конкретный IP, запрос на другой IP не попадёт в этот блок.

Ошибка 500 Internal Server Error: проблема с файлом паролей.

Проверьте путь к файлу в auth_basic_user_file.
Убедитесь, что файл читаем пользователем, от которого запущен Nginx (обычно www-data или nginx).
Проверьте формат файла: каждая строка должна быть вида user:hashed_password.

Экспортер не может подключиться к эндпоинту

Симптом: в логах экспортера ошибки соединения, в Prometheus target «DOWN».

Проверьте сетевую доступность эндпоинта с хоста, где запущен экспортер: curl http://nginx-host:8080/nginx_status.
Если используется Docker, убедитесь, что контейнер экспортера может достичь хоста с Nginx. На Linux используйте --network host или host.docker.internal.
Проверьте учётные данные в URL, если настроена аутентификация.
Проверьте, что IP экспортера добавлен в allow на эндпоинте.

Для комплексной защиты production-среды после настройки мониторинга внедрите продвинутые меры безопасности Nginx: WAF, rate limiting и защиту от slowloris.

Заключение: полная картина мониторинга Nginx

Вы настроили Nginx Status Module, защитили эндпоинт от несанкционированного доступа, научились интерпретировать метрики и подключили их к Prometheus с Grafana. Эта связка даёт базовую, но эффективную систему наблюдаемости, которая работает без лицензионных затрат и внешних зависимостей.

Ключевые точки контроля: активные соединения не должны приближаться к лимиту worker_connections, разница между accepts и handled должна быть нулевой, а requests должны расти предсказуемо в соответствии с нагрузкой. Отклонения - сигнал к немедленному расследованию.

Stub_status не даёт разбивки по виртуальным хостам, не показывает время ответа бэкендов и не детализирует HTTP-коды ответов. Для этих задач потребуется Nginx Plus с расширенным Status API или дополнительные модули вроде ngx_http_vhost_traffic_status_module. Но для 80% сценариев - мониторинг здоровья сервера, выявление аномалий и планирование мощностей - встроенного модуля достаточно.

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