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

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

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

.nginx-lens.yaml в текущей директории
/opt/nginx-lens/config.yaml (с --system)
~/.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).

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

Разработка

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

Лицензия

MIT — см. LICENSE

Metadata

Release files for nginx-lens 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nginx-lens 1.1.0
File	Size	Uploaded
nginx_lens-1.1.0.tar.gz	92.8 kB	May 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nginx-lens 1.1.0
File	Interpreter	ABI	Platform	Reset
nginx_lens-1.1.0-py3-none-any.whl 104.8 kB May 30, 2026	Python 3	none	any	Details

Total release size: 197.6 kB

Release files / nginx_lens-1.1.0.tar.gz

Download URL	nginx_lens-1.1.0.tar.gz
Size	92.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`4bffd05b05babf46057a92909d1be20bde306b6464dd626c7d074fd1f3242f6c`
BLAKE2b-256 checksum How to use checksums	`0b0e977a32689be77f750083fa5413a57492489595ef34efa25b8655bec124ea`
Upload date	May 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`

Release files / nginx_lens-1.1.0-py3-none-any.whl

Download URL	nginx_lens-1.1.0-py3-none-any.whl
Size	104.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`febed54129dc3cbc3e4a3719e90718bb4fdd831b7c15a57fcf44fffbdb69fd07`
BLAKE2b-256 checksum How to use checksums	`1ce726ed7c436f86b6426e1345886f2a79e852725d3f039bf86c459258cc38e8`
Upload date	May 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`