stub_status
Тема дорожной карты · Nginx
Модуль stub_status — встроенный модуль Nginx, предоставляющий простой HTTP-эндпоинт с метриками активности соединений и запросов веб-сервера в реальном времени, обеспечивающий лёгкий мониторинг без каких-либо внешних зависимостей. Для включения stub_status необходимо добавить блок location, например location /nginx_status { stub_status; allow 127.0.0.1; deny all; }, в блок server, ограничивая доступ localhost и возвращая текстовую страницу с активными соединениями, общим числом принятых соединений, обработанных соединений и текущей скоростью запросов. Вывод stub_status состоит из четырёх строк и шести счётчиков — Active connections, accepts, handled, requests, Reading, Writing и Waiting — которые могут опрашиваться инструментами мониторинга, такими как nginx-exporter для Prometheus, или разбираться пользовательскими скриптами для передачи данных в Grafana или Datadog. Поскольку stub_status раскрывает операционные метрики, способные выявить паттерны трафика, доступ к нему всегда должен быть ограничен надёжной мониторинговой инфраструктурой с помощью управления доступом allow/deny или внутреннего блока server на непубличном порту. Модуль stub_status доступен в Nginx с открытым исходным кодом и является основой для всех сторонних интеграций мониторинга Nginx; Nginx Plus заменяет его значительно более богатым эндпоинтом /api/, включающим статистику по upstream, кэшу и зонам.
Как это работает
stub_status использует access_log + error_log. Определите JSON log-формат (log_format json escape=json '{"time":"$time_iso8601",...}';) для лёгкого ingestion в Loki, Elasticsearch, Vector. access_log /path/access.log json; per server-блок. Status-модуль (stub_status) экспонирует базовые метрики; nginx-vts-module даёт полные Prometheus-совместимые метрики. nginx-prometheus-exporter — sidecar-вариант.
Когда применять
Переход на JSON access logs — с первого дня; намного проще запрашивать, чем дефолтный combined-формат. Шлите в Loki через Vector/Promtail. nginx-prometheus-exporter — для метрик. Alerts на 5xx > 1%, пороги latency p95/p99, disk usage log-volume. logrotate — для ротации (или daily + dateext конфиг).
Типичные ошибки
Ловушки stub_status: дефолтный combined-формат лога ломается на спецсимволах (нет эскейпинга); диск забит access-логами без ротации (сервер перестаёт принимать трафик); не логируется X-Real-IP за CDN (видите CDN-IP вместо реальных клиентов); error log на дефолтном warn-уровне пропускает полезное (ставьте info при инцидентах).