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

КраткоСобирайте и визуализируйте логи доступа Nginx (в формате JSON) в ClickStack с помощью приёмника OTel filelog. Включает демо-набор данных и преднастроенную панель мониторинга.

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

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

Необходимые условия

Работающий экземпляр 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 через выделенный конвейер

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

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

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

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

Вариант 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 \
  clickhouse/clickstack-all-in-one:latest

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

Проверка журналов в HyperDX

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

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

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

Демо-набор данных

Для пользователей, которые хотят протестировать интеграцию nginx перед настройкой своих систем в продакшне, мы предоставляем пример набора данных с заранее сгенерированными журналами доступа 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  # Читать с начала для демо-данных
    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" \
  clickhouse/clickstack-all-in-one:latest

Проверьте журналы в HyperDX

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

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

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

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

Панели мониторинга и визуализация

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

конфигурацию панели мониторинга

Импортируйте преднастроенную панель мониторинга

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

Загрузите файл nginx-logs-dashboard.json и нажмите “Finish Import”.

Панель мониторинга будет создана со всеми уже настроенными визуализациями

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

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

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

Убедитесь, что переменная среды CUSTOM_OTELCOL_CONFIG_FILE задана корректно

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

docker exec <container-name> 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 `<container>` cat /var/log/nginx/access.log

Убедитесь, что действующая конфигурация включает ваш ресивер filelog

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

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

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

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

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

Переход в продакшн

В этом руководстве для быстрой настройки используется встроенный в ClickStack OpenTelemetry Collector. Для развертываний в продакшне мы рекомендуем запускать собственный OTel collector и отправлять данные в конечную точку OTLP ClickStack. Сведения о конфигурации для продакшна см. в разделе Отправка данных OpenTelemetry.

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

Необходимые условия

​Настройте формат логирования Nginx

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

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

Вариант 1: Docker Compose

Вариант 2: Docker Run (универсальный образ)

​Проверка журналов в HyperDX

​Демо-набор данных

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

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

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

​Проверьте журналы в HyperDX

​Панели мониторинга и визуализация

​ конфигурацию панели мониторинга

​Импортируйте преднастроенную панель мониторинга

​Панель мониторинга будет создана со всеми уже настроенными визуализациями

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

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

​В HyperDX не отображаются журналы

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

​Переход в продакшн

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

Настройте формат логирования Nginx

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

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

Проверка журналов в HyperDX

Демо-набор данных

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

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

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

Проверьте журналы в HyperDX

Панели мониторинга и визуализация

конфигурацию панели мониторинга

Импортируйте преднастроенную панель мониторинга

Панель мониторинга будет создана со всеми уже настроенными визуализациями

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

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

В HyperDX не отображаются журналы

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

Переход в продакшн