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

Требует подписки Pro плана (или выше) на GetPageSpeed NGINX Extras.

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

RedHat Enterprise Linux 7, 8, 9 и 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-tuning

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-tuning

Включите модуль, добавив следующее в верхнюю часть файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_tuning_module.so;

Этот документ описывает nginx-module-tuning v1.2.0, выпущенный 16 февраля 2026 года.

Рекомендации по настройке 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"
  }
}

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

Функции

Сбор метрик

Размеры заголовков ответа upstream → настройка proxy_buffer_size
Размеры тела ответа upstream → настройка proxy_buffers
Время ответа upstream → настройка 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 (бэкенд слишком медленный)
`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;

    # Разрешить только с localhost и внутренней сети
    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 — понимание всех настроек таймаута