Monitorización de logs de MongoDB con ClickStack

Integración con una instalación existente de MongoDB

Esta sección explica cómo configurar su instalación actual de MongoDB para enviar logs a ClickStack modificando la configuración del OTel collector de ClickStack. Si desea probar la integración de MongoDB antes de configurar su propio entorno, puede usar nuestra configuración predefinida y los datos de ejemplo en la sección "Dataset de demostración".

Requisitos previos

Una instancia de ClickStack en ejecución
Una instalación autogestionada de MongoDB (versión 4.4 o posterior)
Acceso a los archivos de registro de MongoDB

Verifique la configuración de logging de MongoDB

MongoDB 4.4+ genera logs JSON estructurados de forma predeterminada. Compruebe la ubicación de su archivo de registro:

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

Ubicaciones comunes de los logs de MongoDB:

Linux (apt/yum): /var/log/mongodb/mongod.log
macOS (Homebrew): /usr/local/var/log/mongodb/mongo.log
Docker: A menudo se envían a stdout, pero se puede configurar para que escriban en /var/log/mongodb/mongod.log

Si MongoDB está enviando los logs a stdout, configúralo para que escriba en un archivo actualizando mongod.conf:

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

Después de cambiar la configuración, reinicie MongoDB:

# For systemd
sudo systemctl restart mongod

# For Docker
docker restart <mongodb-container>

Cree una configuración personalizada para el OTel collector de MongoDB

ClickStack le permite ampliar la configuración base de OpenTelemetry Collector montando un archivo de configuración personalizado y estableciendo una variable de entorno. La configuración personalizada se fusiona con la configuración base administrada por HyperDX mediante OpAMP.

Cree un archivo llamado mongodb-monitoring.yaml con la siguiente configuración:

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

Configurar ClickStack para cargar una configuración personalizada

Para habilitar una configuración personalizada del collector en su implementación actual de ClickStack, debe:

Montar el archivo de configuración personalizado en /etc/otelcol-contrib/custom.config.yaml
Establecer la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar el directorio de logs de MongoDB para que el collector pueda leerlos

Actualice la configuración de su implementación de ClickStack:

services:
  clickstack:
    # ... configuración existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... otras variables de entorno ...
    volumes:
      - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mongodb:/var/log/mongodb:ro
      # ... otros volúmenes ...

Si está usando la imagen todo en uno con docker, ejecute:

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

Verificar logs en HyperDX

Una vez completada la configuración, inicia sesión en HyperDX y verifica que los logs estén llegando:

Dataset de demostración

Prueba la integración de MongoDB con un dataset de ejemplo pregenerado antes de configurar tus sistemas de producción.

Descarga el dataset de ejemplo

Descarga el archivo de logs de ejemplo:

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

Crea la configuración de prueba del collector

Crea un archivo llamado mongodb-demo.yaml con la siguiente configuración:

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

Ejecuta ClickStack con la configuración de demostración

Ejecuta ClickStack con los logs de demostración y esta configuración:

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

Verifica los logs en HyperDX

Una vez que ClickStack esté en ejecución:

Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una)
Ve a la vista Search y establece el source en Logs
Ajusta el intervalo de tiempo para que incluya 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

Dashboards y visualización

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importar dashboard preconfigurado

Abre HyperDX y ve a la sección Dashboards.
Haz clic en "Import Dashboard" en la esquina superior derecha, en el menú de tres puntos.

Sube el archivo mongodb-logs-dashboard.json y haz clic en "Finish import".

Finalizar la importación del dashboard de logs de MongoDB

El dashboard se creará con todas las visualizaciones preconfiguradas

Para el dataset de demostración, establece el intervalo de tiempo para incluir 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

Solución de problemas

No aparecen logs en HyperDX

Verifique que la configuración efectiva incluya el receiver filelog:

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

Compruebe si hay errores en los logs del collector:

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

Los logs no se procesan correctamente

Verifica que MongoDB esté generando logs en JSON (4.4+):

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

Si la salida no es JSON válido, es posible que tu versión de MongoDB esté usando el formato heredado de registros de texto (anterior a la versión 4.4). Tendrás que reemplazar el operador json_parser por regex_parser o actualizar a MongoDB 4.4+.

Próximos pasos

Configura alertas para eventos críticos (picos de errores, umbrales para consultas lentas)
Crea dashboards adicionales para casos de uso específicos (monitorización de conjuntos de réplicas, seguimiento de conexiones)

Paso a producción

Esta guía amplía el OpenTelemetry Collector integrado de ClickStack para facilitar una configuración rápida. Para implementaciones de producción, recomendamos ejecutar su propio OTel Collector y enviar los datos al endpoint de OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para obtener la configuración de producción.