Мониторинг логов Nginx с помощью ClickStack

Кратко

В этом руководстве показано, как настроить мониторинг Nginx с помощью ClickStack, настроив OTel collector для приёма access-логов Nginx. Вы узнаете, как:

Настроить Nginx на вывод логов в формате JSON
Создать пользовательскую конфигурацию OTel collector для ингестии логов
Развернуть ClickStack с вашей пользовательской конфигурацией
Использовать готовый дашборд для визуализации метрик Nginx

Доступен демонстрационный набор данных с примерами логов, если вы хотите протестировать интеграцию до настройки Nginx в продакшене.

Необходимое время: 5–10 минут

Интеграция с существующим Nginx

В этом разделе описывается, как настроить ваш существующий Nginx для отправки логов в ClickStack путём изменения конфигурации OTel collector в ClickStack. Если вы хотите протестировать интеграцию до настройки собственной среды, вы можете воспользоваться нашей предварительно настроенной конфигурацией и тестовыми данными в следующем разделе.

Предварительные условия

Развёрнутый экземпляр ClickStack
Установленный Nginx
Доступ к изменению файлов конфигурации Nginx

Настройка формата логов Nginx

Сначала настройте Nginx для вывода логов в формате JSON, чтобы упростить их обработку. Добавьте следующее определение формата логов в файл nginx.conf:

Файл nginx.conf обычно расположен по пути:

Linux (apt/yum): /etc/nginx/nginx.conf
macOS (Homebrew): /usr/local/etc/nginx/nginx.conf или /opt/homebrew/etc/nginx/nginx.conf
Docker: конфигурацию обычно монтируют как том

Добавьте это определение формата журнала в блок http:

http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}

После внесения этого изменения перезагрузите Nginx.

Создайте пользовательскую конфигурацию OTel collector

ClickStack позволяет расширить базовую конфигурацию OpenTelemetry Collector путём монтирования пользовательского конфигурационного файла и установки переменной окружения. Пользовательская конфигурация объединяется с базовой конфигурацией, которой управляет HyperDX через OpAMP.

Создайте файл nginx-monitoring.yaml со следующей конфигурацией:

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Эта конфигурация:

Считывает логи Nginx из стандартных путей
Разбирает JSON-записи журнала
Извлекает и сохраняет исходные метки времени журналов
Добавляет атрибут source: nginx для фильтрации в HyperDX
Направляет логи в экспортёр ClickHouse через отдельный конвейер

Примечание

В пользовательской конфигурации вы задаёте только новые receivers и pipelines
Процессоры (memory_limiter, transform, batch) и экспортёры (clickhouse) уже определены в базовой конфигурации ClickStack — достаточно просто ссылаться на них по имени
Оператор time_parser извлекает метки времени из поля time_local сервера Nginx, чтобы сохранить исходное время записей в логах
Конвейеры направляют данные от ваших приёмников к экспортёру ClickHouse через существующие процессоры.

Настройте ClickStack для загрузки пользовательской конфигурации

Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, необходимо:

Смонтируйте файл пользовательской конфигурации в /etc/otelcol-contrib/custom.config.yaml
Установите переменную окружения CUSTOM_OTELCOL_CONFIG_FILE в значение /etc/otelcol-contrib/custom.config.yaml
Смонтируйте каталоги с логами Nginx, чтобы коллектор мог их считывать

Вариант 1: Docker Compose

Обновите конфигурацию развёртывания ClickStack:

services:
  clickstack:
    # ... существующая конфигурация ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... другие переменные окружения ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... другие тома ...

Вариант 2: Docker Run (образ «всё в одном»)

При использовании универсального образа с помощью docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

Примечание

Убедитесь, что коллектор ClickStack имеет необходимые права для чтения файлов журналов nginx. В продакшене используйте монтирование только для чтения (:ro) и следуйте принципу наименьших привилегий.

Проверка логов в HyperDX

После настройки войдите в HyperDX и убедитесь, что журналы поступают:

Перейдите в режим поиска
Выберите Logs в качестве источника и убедитесь, что вы видите записи логов с полями вроде request, request_time, upstream_response_time и т. д.

Вот пример того, что вы должны увидеть:

Демонстрационный набор данных

Для пользователей, которые хотят протестировать интеграцию с nginx перед настройкой продуктивных систем, мы предоставляем образец набора данных с предварительно сгенерированными access‑логами nginx с реалистическими характеристиками трафика.

Загрузка демонстрационного набора данных

# Загрузка логов
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

Набор данных включает:

Записи логов с реалистическими характеристиками трафика
Различные эндпоинты и HTTP‑методы
Как успешные запросы, так и ошибки
Реалистичное время отклика и объём данных в байтах

Создание конфигурации тестового коллектора

Создайте файл с именем nginx-demo.yaml со следующей конфигурацией:

cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # Read from beginning for demo data
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

service:
  pipelines:
    logs/nginx-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Запуск ClickStack с демонстрационной конфигурацией

Запустите ClickStack с демонстрационными логами и конфигурацией:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

Проверка логов в HyperDX

После запуска ClickStack:

Откройте HyperDX и войдите в свою учётную запись (при необходимости сначала создайте её)
Перейдите в раздел Search и установите источник Logs
Установите диапазон времени 2025-10-19 11:00:00 - 2025-10-22 11:00:00

Вот что вы должны увидеть в представлении поиска:

Отображение часового пояса

HyperDX отображает временные метки в часовом поясе вашего браузера. Демонстрационные данные охватывают период 2025-10-20 11:00:00 - 2025-10-21 11:00:00 UTC. Широкий диапазон времени гарантирует, что вы увидите демонстрационные логи независимо от вашего местоположения. После того как вы увидите логи, можно сузить диапазон до 24 часов для более наглядной визуализации.

Дашборды и визуализация

Чтобы помочь вам начать мониторинг nginx с помощью ClickStack, мы предоставляем основные визуализации для Nginx Logs.

Скачать конфигурацию дашборда

Импортируйте готовый дашборд

Откройте HyperDX и перейдите в раздел "Dashboards".
Нажмите "Import Dashboard" в правом верхнем углу под значком с многоточием.

Загрузите файл nginx-logs-dashboard.json и нажмите "Завершить импорт".

Дашборд будет создан со всеми предварительно настроенными визуализациями

Примечание

Для демонстрационного набора данных задайте диапазон времени 2025-10-20 11:00:00 – 2025-10-21 11:00:00 (UTC) (при необходимости скорректируйте под ваш часовой пояс). У импортированного дашборда по умолчанию не будет задан диапазон времени.

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

Пользовательская конфигурация не загружается

Убедитесь, что переменная окружения CUSTOM_OTELCOL_CONFIG_FILE установлена корректно

docker exec <имя-контейнера> printenv CUSTOM_OTELCOL_CONFIG_FILE

Проверьте, что пользовательский конфигурационный файл смонтирован по пути /etc/otelcol-contrib/custom.config.yaml

docker exec <имя-контейнера> ls -lh /etc/otelcol-contrib/custom.config.yaml

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

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

В HyperDX не отображаются логи

Убедитесь, что nginx пишет логи в формате JSON

tail -f /var/log/nginx/access.log

Убедитесь, что коллектор может читать логи

docker exec `<контейнер>` cat /var/log/nginx/access.log

Убедитесь, что в фактической конфигурации присутствует ваш приёмник filelog

docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog

Проверьте журналы коллектора на наличие ошибок

docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

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

Если вы хотите продолжить изучение, вот несколько следующих шагов для экспериментов с вашим дашбордом:

Настройте оповещения для критически важных метрик (уровень ошибок, пороги задержки)
Создайте дополнительные дашборды для конкретных сценариев использования (мониторинг API, события безопасности)

Интеграция с существующим Nginx​

Предварительные условия​

Настройка формата логов Nginx​

Создайте пользовательскую конфигурацию OTel collector​

Настройте ClickStack для загрузки пользовательской конфигурации​

Вариант 1: Docker Compose​

Вариант 2: Docker Run (образ «всё в одном»)​

Проверка логов в HyperDX​

Демонстрационный набор данных​

Загрузка демонстрационного набора данных​

Создание конфигурации тестового коллектора​

Запуск ClickStack с демонстрационной конфигурацией​

Проверка логов в HyperDX​

Дашборды и визуализация​

Скачать конфигурацию дашборда​

Импортируйте готовый дашборд​

Дашборд будет создан со всеми предварительно настроенными визуализациями​

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

Пользовательская конфигурация не загружается​

В HyperDX не отображаются логи​

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

Интеграция с существующим Nginx

Предварительные условия

Настройка формата логов Nginx

Создайте пользовательскую конфигурацию OTel collector

Настройте ClickStack для загрузки пользовательской конфигурации

Вариант 1: Docker Compose

Вариант 2: Docker Run (образ «всё в одном»)

Проверка логов в HyperDX

Демонстрационный набор данных

Загрузка демонстрационного набора данных

Создание конфигурации тестового коллектора

Запуск ClickStack с демонстрационной конфигурацией

Проверка логов в HyperDX

Дашборды и визуализация

Скачать конфигурацию дашборда

Импортируйте готовый дашборд

Дашборд будет создан со всеми предварительно настроенными визуализациями

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

Пользовательская конфигурация не загружается

В HyperDX не отображаются логи

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