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

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

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

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

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

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

Проверьте конфигурацию логирования 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>

Создайте пользовательскую конфигурацию 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, чтобы избежать повторного приёма журналов при перезапуске коллектора.

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

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

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

Docker Compose
Docker Run (All-in-One Image)

Обновите конфигурацию развертывания 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-образ 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) и следуйте принципу наименьших привилегий.

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

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

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

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

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

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

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

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

Создайте файл 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

Запустите 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:

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

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

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

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

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

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

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

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

Возможности

Руководства

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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