nginx-lens 1.1.0

CLI-инструмент для анализа, визуализации и диагностики конфигураций Nginx

nginx-lens

CLI-инструмент для анализа, визуализации и диагностики конфигураций Nginx.

Проверяет upstream, находит проблемы в конфиге, анализирует логи и экспортирует отчёты в JSON/YAML/Prometheus. Опционально — HTTP-агенты и hub для централизованного мониторинга через UI.

Установка

pip install nginx-lens
# или изолированно
pipx install nginx-lens
# или из исходников
git clone https://github.com/rainysundaynight/nginx-lens.git
cd nginx-lens && pipx install .

Web-стек (agent + hub):

pip install nginx-lens[web]

Инициализация конфига и автодополнения:

nginx-lens init
# системный конфиг (root):
sudo nginx-lens init --system

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

# Проверка upstream
nginx-lens health /etc/nginx/nginx.conf

# Статический анализ (SSL, limits, rewrites, conflicts)
nginx-lens analyze /etc/nginx/nginx.conf

# Комплексная валидация для CI/CD
nginx-lens validate /etc/nginx/nginx.conf --json

# Какой location обработает URL
nginx-lens route http://example.com/api/v1/users

# Анализ access.log
nginx-lens logs /var/log/nginx/access.log --top 20

# Метрики конфигурации + Prometheus
nginx-lens metrics /etc/nginx/nginx.conf --prometheus

Web-архитектура

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  nginx-host │     │  nginx-host │     │     UI      │
│   :8088     │     │   :8088     │     │  (browser)  │
│   agent     │     │   agent     │     └──────┬──────┘
└──────┬──────┘     └──────┬──────┘            │
       │                   │                   │
       └─────────┬─────────┘                   │
                 ▼                             │
          ┌─────────────┐                      │
          │ nginx-lens  │◄─────────────────────┘
          │    hub      │   GET /api/v1/*
          │   :8089     │
          └─────────────┘

На каждом nginx-сервере — nginx-lens-agent. Hub агрегирует snapshot с агентов; UI подключается к hub API.

Подробнее: docs/WEB_DEPLOYMENT.md

Основные команды

Команда	Назначение
health	Доступность upstream (TCP/HTTP), DNS
resolve	DNS-резолвинг upstream
analyze	Статический анализ конфигурации
validate	syntax + analyze + upstream (для CI)
syntax	nginx -t с подсветкой ошибок
tree / graph / include-tree	Визуализация конфигурации
route	Маршрутизация URL → server/location
diff	Сравнение двух конфигов
logs	Статистика и аномалии в логах
metrics	Метрики конфигурации, Prometheus
upstreams	Сводка по upstream-блокам
config	Активный конфиг nginx-lens
init / completion	Первичная настройка

Полный справочник: docs/CONFIGURATION.md

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

Файлы (по приоритету):

1. .nginx-lens.yaml в текущей директории
2. /opt/nginx-lens/config.yaml (с --system)
3. ~/.nginx-lens/config.yaml (по умолчанию после init)

Переменные окружения: префикс NGINX_LENS_ (например NGINX_LENS_TIMEOUT).

Пример: example-config.yaml

Ограничения парсера

Парсер regex-based — не полный nginx grammar. Edge cases: include с переменными, сложные if, многострочные директивы. Для синтаксиса используйте nginx-lens syntax (nginx -t).

Документация

• Конфигурация и команды
• Web-деплой (agent + hub + UI)
• ngx_dynamic_upstream
• CHANGELOG

Разработка

pip install -e ".[dev,web]"
pytest tests/ -v

Лицензия

MIT — см. LICENSE