Мониторинг журналов MongoDB с ClickStack

Мониторинг журналов MongoDB с ClickStack

Кратко

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

​

Интеграция с существующей MongoDB

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

​

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

• Работающий экземпляр ClickStack
• Существующее самоуправляемое развертывание MongoDB (версии 4.4 или новее)
• Доступ к файлам журналов MongoDB

1. ​

   Проверьте конфигурацию логирования MongoDB

   MongoDB 4.4+ по умолчанию выводит структурированные логи в формате JSON. Проверьте путь к файлу журнала:

   cat /etc/mongod.conf | grep -A 5 systemLog
   

   Распространённые пути к журналам MongoDB:

   • Linux (apt/yum): /var/log/mongodb/mongod.log
   • macOS (Homebrew): /usr/local/var/log/mongodb/mongo.log
   • Docker: Часто выводится в stdout, но можно настроить запись в /var/log/mongodb/mongod.log

   Если MongoDB выводит логи в stdout, настройте запись в файл, обновив mongod.conf:

   systemLog:
     destination: file
     path: /var/log/mongodb/mongod.log
     logAppend: true
   

   После изменения конфигурации перезапустите MongoDB:

   # Для systemd
   sudo systemctl restart mongod
   
   # Для Docker
   docker restart <mongodb-container>
   
2. ​

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

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

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

   receivers:
     filelog/mongodb:
       include:
         - /var/log/mongodb/mongod.log
       start_at: beginning
       operators:
         - type: json_parser
           parse_from: body
           parse_to: attributes
           timestamp:
             parse_from: attributes.t.$$date
             layout: '2006-01-02T15:04:05.000-07:00'
             layout_type: gotime
           severity:
             parse_from: attributes.s
             overwrite_text: true
             mapping:
               fatal: F
               error: E
               warn: W
               info: I
               debug:
                 - D1
                 - D2
                 - D3
                 - D4
                 - D5
   
         - type: move
           from: attributes.msg
           to: body
   
         - type: add
           field: attributes.source
           value: "mongodb"
   
         - type: add
           field: resource["service.name"]
           value: "mongodb-production"
   
   service:
     pipelines:
       logs/mongodb:
         receivers: [filelog/mongodb]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   

   • В пользовательской конфигурации вы определяете только новые приёмники и конвейеры. Процессоры (memory_limiter, transform, batch) и экспортёры (clickhouse) уже определены в базовой конфигурации ClickStack — вы просто ссылаетесь на них по имени.
   • В этой конфигурации используется start_at: beginning, чтобы при запуске коллектора читать все существующие журналы. Для промышленных развертываний замените на start_at: end, чтобы избежать повторного приёма журналов при перезапуске коллектора.
3. ​

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

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

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

   Docker Compose

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

   services:
     clickstack:
       # ... existing configuration ...
       environment:
         - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
         # ... other environment variables ...
       volumes:
         - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
         - /var/log/mongodb:/var/log/mongodb:ro
         # ... other volumes ...
   

   Docker Run (All-in-One Image)

   Если вы используете Docker-образ all-in-one, выполните:

   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)/mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v /var/log/mongodb:/var/log/mongodb:ro \
     clickhouse/clickstack-all-in-one:latest
   

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

4. ​

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

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

​

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

Протестируйте интеграцию MongoDB с заранее подготовленным демо-набором данных, прежде чем настраивать свои промышленные системы.

1. ​

   Скачайте демо-набор данных

   Скачайте пример файла журнала:

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mongodb/mongod.log
   
2. ​

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

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

   cat > mongodb-demo.yaml << 'EOF'
   receivers:
     filelog/mongodb:
       include:
         - /tmp/mongodb-demo/mongod.log
       start_at: beginning
       operators:
         - type: json_parser
           parse_from: body
           parse_to: attributes
           timestamp:
             parse_from: attributes.t.$$date
             layout: '2006-01-02T15:04:05.000-07:00'
             layout_type: gotime
           severity:
             parse_from: attributes.s
             overwrite_text: true
             mapping:
               fatal: F
               error: E
               warn: W
               info: I
               debug:
                 - D1
                 - D2
                 - D3
                 - D4
                 - D5
   
         - type: move
           from: attributes.msg
           to: body
   
         - type: add
           field: attributes.source
           value: "mongodb-demo"
   
         - type: add
           field: resource["service.name"]
           value: "mongodb-demo"
   
   service:
     pipelines:
       logs/mongodb-demo:
         receivers: [filelog/mongodb]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   EOF
   
3. ​

   Запустите 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)/mongodb-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v "$(pwd)/mongod.log:/tmp/mongodb-demo/mongod.log:ro" \
     clickhouse/clickstack-all-in-one:latest
   

   ​

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

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

   1. Откройте HyperDX и войдите в свою учётную запись (возможно, сначала потребуется создать её)
   2. Перейдите в Search view и установите источник Logs
   3. Установите временной диапазон, включающий 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

​

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

1. ​

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

2. ​

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

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

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

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

   Для демо-набора данных установите временной диапазон 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

​

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

​

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

Проверьте, что в применяемой конфигурации указан ваш приёмник filelog:

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

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

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

​

Не удаётся корректно разобрать журналы

Убедитесь, что MongoDB выводит журналы в формате JSON (4.4+):

tail -1 /var/log/mongodb/mongod.log | python3 -m json.tool

Если вывод не является корректным JSON, возможно, в вашей версии MongoDB используется устаревший текстовый формат логирования (до версии 4.4). Вам потребуется заменить оператор json_parser на regex_parser или обновить MongoDB до версии 4.4 и выше.

​

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

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

​

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

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