tuning: Модуль советника по настройке NGINX

Установка на Debian/Ubuntu

Эти документы применимы к APT-пакету nginx-module-tuning, предоставляемому репозиторием GetPageSpeed Extras.

Настройте APT репозиторий, как описано в настройке APT репозитория.
Установите модуль:

sudo apt-get update
sudo apt-get install nginx-module-tuning

Показать дистрибутивы и архитектуры

| Дистрибутив | Версия           | Компонент   | Архитектуры    |
|-------------|------------------|-------------|-----------------|
| debian      | bookworm         | main        | amd64, arm64    |
| debian      | bookworm-mainline| main        | amd64, arm64    |
| debian      | trixie           | main        | amd64, arm64    |
| debian      | trixie-mainline  | main        | amd64, arm64    |
| ubuntu      | focal            | main        | amd64, arm64    |
| ubuntu      | focal-mainline   | main        | amd64, arm64    |
| ubuntu      | jammy            | main        | amd64, arm64    |
| ubuntu      | jammy-mainline   | main        | amd64, arm64    |
| ubuntu      | noble            | main        | amd64, arm64    |
| ubuntu      | noble-mainline   | main        | amd64, arm64    |

Рекомендации по настройке NGINX на основе данных из реального трафика

Прекратите гадать о размерах буферов. Этот модуль наблюдает за вашими фактическими паттернами трафика и говорит вам точно, что настраивать.

Проблема

Каждое руководство по настройке прокси NGINX говорит вам настраивать proxy_buffer_size, proxy_buffers и таймауты. Но какие значения следует использовать?

Традиционный подход включает запуск команд curl против ваших бэкендов:

curl -s -w %{size_header} -o /dev/null https://backend.example.com

Это дает вам одну точку данных. Ваш реальный трафик имеет тысячи запросов в минуту, каждый с разными размерами заголовков, размерами тел и временем ответа. Один curl ничего не говорит вам о 95-м процентиле, который вызывает ошибки upstream sent too big header в производстве.

Решение

Этот модуль находится внутри NGINX, пассивно наблюдает за каждым проксируемым запросом и строит гистограммы фактического трафика. Когда вы будете готовы, запросите конечную точку /tuning-advisor:

{
  "sample_size": 847293,
  "uptime_seconds": 86400,
  "requests_per_second": 9.81,

  "proxy_buffer_size": {
    "observed": { "avg": "1.8k", "max": "23.4k", "p95_approx": "4.0k" },
    "recommendation": "OK",
    "suggested_value": "4k",
    "reason": "95% заголовков помещаются в 4k"
  },

  "proxy_buffers": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "8 4k",
    "reason": "По умолчанию 32k (8x4k) достаточно для 95% ответов"
  },

  "nginx_config": {
    "snippet": "proxy_buffer_size 4k;\nproxy_buffers 8 4k;\nproxy_read_timeout 10s;\nclient_body_buffer_size 8k;",
    "apply_to": "http, server, or location block"
  }
}

Скопируйте фрагмент, вставьте его в свою конфигурацию, перезагрузите. Готово.

Особенности

Сбор метрик

Размеры заголовков ответов от серверов → настройте proxy_buffer_size
Размеры тел ответов от серверов → настройте proxy_buffers
Время ответов от серверов → настройте proxy_read_timeout
Размеры тел запросов от клиентов → настройте client_body_buffer_size
Коэффициенты повторного использования соединений → оптимизируйте параметры keepalive
Частота попадания/промахов в кэше → оцените эффективность кэша прокси

Производительность

Безблокирующие атомы — без мьютексов, без конфликта между рабочими процессами
Общая память — все рабочие процессы вносят вклад в одни и те же счетчики
Процентили на основе гистограммы — приблизительные p95/p99 без хранения каждого значения
Наносекундные накладные расходы — ~10 атомарных инкрементов на запрос

Форматы вывода

JSON API с рекомендациями, причинами и готовыми к использованию фрагментами конфигурации
Метрики Prometheus для интеграции с Grafana, Alertmanager и т.д.
Точка сброса для очистки счетчиков и начала новых окон наблюдений

Быстрый старт

load_module modules/ngx_http_tuning_module.so;

http {
    # Включите сбор метрик для всех проксируемых запросов
    tuning_advisor on;

    server {
        # Откройте конечную точку настройки (ограничьте доступ!)
        location = /tuning-advisor {
            tuning_advisor_status;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

        location / {
            proxy_pass http://backend;
        }
    }
}

Затем запросите её:

curl http://localhost/tuning-advisor | jq .

Справочник по конфигурации

tuning_advisor

tuning_advisor on | off;


По умолчанию	`off`
Контекст	`http`, `server`, `location`

Включает сбор метрик для проксируемых запросов в этом контексте.

tuning_advisor_shm_size

tuning_advisor_shm_size 1m;


По умолчанию	`1m`
Контекст	`http`

Размер зоны общей памяти для агрегации метрик между рабочими процессами. 1 МБ вполне достаточно для счетчиков фиксированного размера и гистограмм.

tuning_advisor_status

tuning_advisor_status;


Контекст	`location`

Включает обработчик статуса. Отвечает на GET (возвращает метрики), POST (сбрасывает метрики) и GET с ?reset (также сбрасывает).

API Справочник

GET /tuning-advisor

Возвращает JSON с наблюдаемыми метриками, рекомендациями и готовым к использованию фрагментом конфигурации.

Структура ответа:

Раздел	Описание
`sample_size`	Общее количество проксируемых запросов, наблюдаемых
`uptime_seconds`	Секунды с момента начала сбора (или последнего сброса)
`requests_per_second`	Средняя скорость запросов
`proxy_buffer_size`	Метрики размеров заголовков и рекомендации
`proxy_buffers`	Метрики размеров тел и рекомендации
`proxy_read_timeout`	Метрики времени отклика и рекомендации
`client_body_buffer_size`	Метрики тел запросов и рекомендации
`connection_reuse`	Эффективность keepalive для клиента и upstream
`proxy_cache`	Статистика попаданий/промахов/обходов кэша
`nginx_config`	Фрагмент конфигурации для копирования и вставки
`histograms`	Сырые подсчеты ведер для пользовательского анализа

GET /tuning-advisor?prometheus

Возвращает формат экспозиции Prometheus:

## HELP nginx_tuning_requests_total Общее количество проксируемых запросов
## TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

## HELP nginx_tuning_header_size_bucket Распределение размеров заголовков
## TYPE nginx_tuning_header_size_bucket histogram
nginx_tuning_header_size_bucket{le="1024"} 423841
nginx_tuning_header_size_bucket{le="2048"} 712453
nginx_tuning_header_size_bucket{le="4096"} 831029
nginx_tuning_header_size_bucket{le="+Inf"} 847293

Настройте сбор Prometheus:

scrape_configs:
  - job_name: nginx-tuning
    metrics_path: /tuning-advisor
    params:
      prometheus: ['1']
    static_configs:
      - targets: ['nginx:80']

POST /tuning-advisor

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

GET /tuning-advisor?reset

То же самое, что и POST — сбрасывает все метрики.

Логика рекомендаций

Модуль анализирует процентиль и предоставляет практические рекомендации:

Метрика	Рекомендация	Когда
`proxy_buffer_size`	`OK`	p95 размер заголовка ≤ 4KB
	`INCREASE`	p95 > 4KB (предложение 8k, 16k или 32k)
	`WARNING`	p95 > 16KB (исследуйте upstream)
`proxy_buffers`	`OK`	p95 размер тела ≤ 32KB
	`INCREASE`	p95 > 32KB (предложение больших буферов)
`proxy_read_timeout`	`CONSIDER_REDUCING`	p99 время ответа < 5s
	`OK`	p99 между 5s и 30s
	`WARNING`	p99 > 30s (backend слишком медленный)
`connection_reuse`	`EXCELLENT`	Клиент ≥ 80% повторного использования, upstream ≥ 70%
	`WARNING`	Низкое повторное использование (предложение настройки keepalive)
`proxy_cache`	`EXCELLENT`	Коэффициент попаданий ≥ 80%
	`WARNING`	Коэффициент попаданий < 20%
##

Гистограммы

Модуль использует экспоненциальные ведерные гистограммы для приближения процентилей без хранения каждого значения:

Ведра размеров: <1k, 1-2k, 2-4k, 4-8k, 8-16k, 16-32k, 32-64k, >64k

Ведра времени: <10ms, 10-50ms, 50-100ms, 100-500ms, 500ms-1s, 1-5s, 5-10s, >10s

Сырые подсчеты ведер доступны в разделе histograms JSON-ответа для пользовательского анализа.

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

Конечная точка /tuning-advisor раскрывает информацию о ваших паттернах трафика. Всегда ограничивайте доступ:

location = /tuning-advisor {
    tuning_advisor_status;

    # Разрешите доступ только с локального хоста и внутренней сети
    allow 127.0.0.1;
    allow ::1;
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all;

    # Или требуйте аутентификацию
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

Связанное чтение

Настройка proxy_buffer_size в NGINX — глубокое погружение в размеры буферов
Параметры таймаута NGINX объяснены — понимание всех параметров таймаута