Плагин Nginx

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

Обзор

Плагин Nginx собирает метрики из модуля stub_status Nginx, в том числе:

• Статистика соединений — активные соединения, принятые и обработанные соединения
• Метрики запросов — общее число запросов, запросов в секунду
• Состояния воркеров — соединения в состоянии чтения, записи, ожидания
• Частота соединений — частота принятия/сброса соединений

Требования

Версия Nginx

• Любая версия со скомпилированным модулем stub_status
• Наиболее распространённые: Nginx 1.14+, 1.18+, 1.20+, 1.22+, 1.24+
• Протестировано с: Nginx 1.18, 1.20, 1.22, 1.24, 1.25

Зависимости Python

pip install requests>=2.28.0

Устанавливается автоматически при использовании PLUGINS=nginx во время установки агента.

Модуль Nginx

Nginx должен быть скомпилирован с http_stub_status_module:

# Check if module is available
nginx -V 2>&1 | grep -o with-http_stub_status_module

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

Примечание: Большинство готовых пакетов Nginx включают этот модуль по умолчанию.

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

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

plugins:
  nginx:
    enabled: true
    status_url: http://127.0.0.1/nginx_status

Пользовательский URL статуса

plugins:
  nginx:
    enabled: true
    status_url: http://127.0.0.1:8080/status

Удалённый сервер Nginx

plugins:
  nginx:
    enabled: true
    status_url: http://nginx-server.example.com/nginx_status

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

plugins:
  nginx:
    enabled: true                                # Enable/disable plugin
    status_url: http://127.0.0.1/nginx_status    # Nginx stub_status URL
    timeout: 5                                   # Request timeout in seconds

Переменные окружения

Конфигурацию можно переопределить с помощью переменных окружения:

export NGINX_STATUS_URL="http://127.0.0.1/nginx_status"

Настройка Nginx

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

Отредактируйте файл конфигурации Nginx (например, /etc/nginx/sites-available/default или /etc/nginx/nginx.conf):

Вариант 1: Выделенный server-блок (рекомендуется)

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Вариант 2: Добавление в существующий server-блок

server {
    listen 80;
    server_name example.com;

    # Your existing configuration...

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Вариант 3: Пользовательский порт

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location /status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Соображения безопасности

Важно: Всегда ограничивайте доступ к stub_status:

location /nginx_status {
    stub_status on;
    access_log off;

    # Only allow localhost
    allow 127.0.0.1;
    allow ::1;
    deny all;
}

Для удалённого мониторинга:

location /nginx_status {
    stub_status on;
    access_log off;

    # Allow specific monitoring server IP
    allow 10.0.0.100;  # Agent server IP
    deny all;
}

Проверка конфигурации

# Check Nginx configuration syntax
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

# Test stub_status endpoint
curl http://127.0.0.1/nginx_status

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

Active connections: 5
server accepts handled requests
 1234 1234 5678
Reading: 0 Writing: 1 Waiting: 4

Собираемые метрики

Метрики соединений

Частота сброса соединений:

drop_rate = dropped_connections / accepts_total

Норма: drop_rate = 0 (нет сброшенных соединений)

Метрики состояния воркеров

Объяснение состояний соединений:

• Reading: Nginx читает заголовок запроса от клиента
• Writing: Nginx отправляет ответ обратно клиенту
• Waiting: keep-alive соединения, ожидающие новых запросов

Мониторинг:

• Высокое значение reading = медленные клиенты или большие заголовки запросов
• Высокое значение writing = медленные клиенты или большие ответы
• Высокое значение waiting = много keep-alive соединений (нормально)

Метрики на дашборде

Дашборд StatusRadar отображает:

Карточка обзора

• Status — сервер Nginx работает/не работает
• Active Connections — текущие соединения
• Requests/sec — частота запросов

График соединений

• Активные соединения во времени
• Принятые против обработанных соединений
• Частота сброса соединений

График состояний воркеров

• Соединения в состоянии чтения
• Соединения в состоянии записи
• Соединения в состоянии ожидания

График частоты запросов

• Запросов в секунду
• Всего запросов (накопительно)

Установка

Быстрая установка

PLUGINS='nginx' \
NGINX_STATUS_URL='http://127.0.0.1/nginx_status' \
TOKEN='your-agent-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Установка на существующий агент

1. Настройте stub_status в Nginx:

   sudo nano /etc/nginx/sites-available/default

   Добавьте:

   location /nginx_status {
       stub_status on;
       access_log off;
       allow 127.0.0.1;
       deny all;
   }

2. Перезагрузите Nginx:

   sudo nginx -t && sudo systemctl reload nginx

3. Проверьте эндпоинт:

   curl http://127.0.0.1/nginx_status

4. Включите плагин в конфигурации агента:

   sudo nano /opt/statusradar/config/agent.yaml

   Добавьте:

   plugins:
     nginx:
       enabled: true
       status_url: http://127.0.0.1/nginx_status

5. Перезапустите агент:

   sudo systemctl restart statusradar-agent

6. Проверьте:

   sudo journalctl -u statusradar-agent -n 50 --no-pager | grep nginx

   Ожидается:

   INFO: Plugin nginx: Metrics collected successfully

Тестирование

Ручной тест плагина

cd /opt/statusradar
python3 plugins/nginx_plugin.py

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

Plugin: nginx
Enabled: True
Available: True

Collecting metrics...
{
  "active_connections": 5,
  "accepts_total": 12345,
  "handled_total": 12345,
  "requests_total": 67890,
  "dropped_connections": 0,
  "reading": 0,
  "writing": 1,
  "waiting": 4,
  "requests_per_sec": 12.5,
  "accepts_per_sec": 2.1
}

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

# Local test
curl http://127.0.0.1/nginx_status

# With specific port
curl http://127.0.0.1:8080/status

# Remote server
curl http://nginx-server.example.com/nginx_status

# Verbose output
curl -v http://127.0.0.1/nginx_status

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

Active connections: 5
server accepts handled requests
 12345 12345 67890
Reading: 0 Writing: 1 Waiting: 4

Устранение неполадок

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

Проверка 1: Запущен ли Nginx?

sudo systemctl status nginx

Проверка 2: Настроен ли stub_status?

curl http://127.0.0.1/nginx_status

Проверка 3: Доступен ли модуль stub_status?

nginx -V 2>&1 | grep http_stub_status_module

Проверка 4: Проверьте конфигурацию агента

cat /opt/statusradar/config/agent.yaml | grep -A3 nginx

Проверка 5: Проверьте логи агента

sudo journalctl -u statusradar-agent -n 100 --no-pager | grep nginx

Распространённые ошибки

"Connection refused"

Ошибка:

ERROR: Plugin nginx: Connection refused

Причины:

1. Nginx не запущен
2. Неверный URL в конфигурации
3. stub_status не слушает ожидаемый адрес/порт

Решение:

# Check if Nginx is running
sudo systemctl status nginx

# Check Nginx is listening on expected port
sudo netstat -tlnp | grep nginx

# Test URL manually
curl http://127.0.0.1/nginx_status

# Check Nginx configuration
sudo nginx -T | grep stub_status

"HTTP 404 Not Found"

Ошибка:

ERROR: Plugin nginx: HTTP 404 Not Found

Причина: location для stub_status не настроен или неверный URL

Решение:

# Check Nginx configuration for stub_status
sudo nginx -T | grep -A5 stub_status

# Verify location path
# If configured as '/status', use: http://127.0.0.1/status
# If configured as '/nginx_status', use: http://127.0.0.1/nginx_status

Обновите конфигурацию агента с корректным URL:

plugins:
  nginx:
    status_url: http://127.0.0.1/nginx_status  # Match your Nginx config

"HTTP 403 Forbidden"

Ошибка:

ERROR: Plugin nginx: HTTP 403 Forbidden

Причина: IP-адрес не разрешён в конфигурации Nginx

Решение:

Отредактируйте конфигурацию Nginx:

location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;  # Add agent's IP address
    deny all;
}

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

sudo nginx -t && sudo systemctl reload nginx

"stub_status module not available"

Ошибка:

ERROR: Plugin nginx: stub_status not available

Причина: Nginx скомпилирован без модуля stub_status

Решение:

Проверьте доступность модуля:

nginx -V 2>&1 | grep http_stub_status_module

Если модуль недоступен, вам нужно:

1. Установить Nginx из официального репозитория (включает модуль)
2. Или перекомпилировать Nginx с --with-http_stub_status_module

Установка Nginx с stub_status (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install nginx

Метрики показывают неожиданные значения

Симптом: Метрики не соответствуют ожиданиям

Отладка:

# View raw stub_status output
curl http://127.0.0.1/nginx_status

# Check Nginx access log
sudo tail -f /var/log/nginx/access.log

# Check Nginx error log
sudo tail -f /var/log/nginx/error.log

# Check active workers
ps aux | grep nginx | grep worker

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

На Nginx

Незначительное влияние:

• stub_status предоставляет предварительно рассчитанные счётчики
• Нет дополнительной нагрузки на обработку
• Время отклика < 1 мс
• Нулевое влияние на обработку запросов

Бенчмарк:

• RPS Nginx с мониторингом: 50 000+ RPS
• RPS Nginx без мониторинга: 50 000+ RPS
• Накладные расходы: 0%

На агент

Использование ресурсов:

• Память: +5 МБ
• CPU: +1% во время сбора (0.1–0.2 секунды)
• Сеть: +0.5 КБ за сбор

Сценарии использования

1. Мониторинг соединений

Отслеживайте:

• Активные соединения
• Частоту принятия соединений
• Частоту сброса соединений (accepts - handled)

Оповещение при:

• Всплеске активных соединений (DDoS?)
• Сбросах соединений > 0 (исчерпание ресурсов)
• Активных соединениях > лимита worker_connections

2. Отслеживание частоты запросов

Отслеживайте:

• Запросов в секунду
• Тренды роста запросов
• Шаблоны запросов (время суток)

Оповещение при:

• Резком падении RPS (проблема приложения)
• Необычном всплеске RPS
• RPS, превышающем пропускную способность

3. Анализ состояния воркеров

Отслеживайте:

• Распределение reading/writing/waiting
• Долю соединений в ожидании
• Эффективность воркеров

Оповещение при:

• Высоком значении reading (медленные клиенты)
• Высоком значении writing (медленный бэкенд или большие ответы)
• Загруженности всех воркеров

4. Оптимизация keep-alive

Отслеживайте:

• Соединения в ожидании (keep-alive)
• Соотношение активных и ожидающих

Оптимизируйте:

• Настройку keepalive_timeout
• Настройку keepalive_requests
• Баланс между переиспользованием соединений и памятью

Лучшие практики

1. Защитите эндпоинт stub_status

Всегда ограничивайте доступ:

location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    allow ::1;
    deny all;
}

Никогда не открывайте публично:

# BAD - Don't do this!
location /nginx_status {
    stub_status on;
    # No access restrictions = security risk!
}

2. Отключите логирование доступа

stub_status генерирует частые запросы, логировать их не нужно:

location /nginx_status {
    stub_status on;
    access_log off;  # Important: reduces I/O
    allow 127.0.0.1;
    deny all;
}

3. Используйте localhost для локального мониторинга

# Good - fast, secure
plugins:
  nginx:
    status_url: http://127.0.0.1/nginx_status

# Avoid - unnecessary network overhead
plugins:
  nginx:
    status_url: http://hostname.example.com/nginx_status

4. Отслеживайте лимиты соединений

Знайте свои лимиты:

# Check worker connections
grep worker_connections /etc/nginx/nginx.conf

Пример:

events {
    worker_connections 1024;  # Max connections per worker
}

При 4 воркерах: Максимум = 4 * 1024 = 4096 соединений

Настройте оповещение: active_connections > 3000 (75% от максимума)

5. Оптимизируйте под свою нагрузку

Для API-серверов (в основном JSON-ответы):

• Меньший keepalive_timeout (10–30 секунд)
• Больший keepalive_requests (100+)

Для статического контента:

• Больший keepalive_timeout (65 секунд)
• Стандартный keepalive_requests (100)

Расширенная конфигурация

Несколько экземпляров Nginx

Для мониторинга нескольких экземпляров Nginx на одном сервере:

Вариант 1: Разные порты

Экземпляр 1:

plugins:
  nginx:
    status_url: http://127.0.0.1:8080/nginx_status

Экземпляр 2: Разверните отдельный агент.

Вариант 2: Разные URL

В настоящее время не поддерживается в одном агенте — используйте отдельные агенты.

HTTPS-эндпоинт статуса

server {
    listen 127.0.0.1:443 ssl;
    server_name localhost;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Конфигурация агента:

plugins:
  nginx:
    status_url: https://127.0.0.1/nginx_status

Пользовательский путь статуса

location /private/monitoring/nginx {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

Конфигурация агента:

plugins:
  nginx:
    status_url: http://127.0.0.1/private/monitoring/nginx

Примеры конфигураций

Базовый веб-сервер

# /etc/nginx/sites-available/default
server {
    listen 80;
    server_name example.com;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Обратный прокси

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Балансировщик нагрузки

upstream backend {
    server backend1.example.com;
    server backend2.example.com;
}

server {
    listen 80;
    server_name lb.example.com;

    location / {
        proxy_pass http://backend;
    }

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Интерпретация метрик

Понимание активных соединений

Active connections = reading + writing + waiting

Пример:

Active connections: 100
Reading: 5 Writing: 10 Waiting: 85

Интерпретация:

• 100 всего активных соединений
• 5 клиентов отправляют запросы
• 10 клиентов получают ответы
• 85 простаивающих keep-alive соединений

Статистика соединений

server accepts handled requests
 12345 12345 67890

Означает:

• 12 345 принятых соединений
• 12 345 обработанных соединений (без сбросов)
• 67 890 всего запросов
• В среднем 5.5 запросов на соединение (67890 / 12345)

Если accepts > handled:

• Часть соединений была сброшена
• Возможные причины: лимиты ресурсов, проблемы конфигурации

Расчёт метрик

Запросов на соединение:

rpc = total_requests / total_handled_connections

Высокое значение = хорошее использование keep-alive

Частота сброса соединений:

drop_rate = (accepts - handled) / accepts

Должно быть 0%

Следующие шаги

• Просмотреть все плагины
• Плагин Apache
• Плагин PHP-FPM
• Плагин Varnish
• Руководство по конфигурации агента