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

Интеграция с существующим 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 через выделенный конвейер

Настройка 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:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

Вариант 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

Проверка журналов в 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:

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

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

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

Скачать файл конфигурации панели мониторинга.

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

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

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

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

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

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

Убедитесь, что переменная среды 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 с конфигурацией для продакшн.