Supervision des logs MongoDB avec ClickStack

Intégration avec une instance MongoDB existante

Cette section explique comment configurer votre installation MongoDB existante pour envoyer des logs à ClickStack en modifiant la configuration du ClickStack OTel collector. Si vous souhaitez tester l’intégration MongoDB avant de configurer votre propre environnement, vous pouvez utiliser notre configuration préconfigurée et des données d’exemple dans la section "Jeu de données de démonstration".

Prérequis

Instance ClickStack opérationnelle
Installation MongoDB auto-gérée existante (version 4.4 ou ultérieure)
Accès aux fichiers journaux de MongoDB

Vérifier la configuration de journalisation de MongoDB

MongoDB 4.4+ génère par défaut des logs JSON structurés. Vérifiez l’emplacement de votre fichier de logs :

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

Emplacements courants des journaux MongoDB :

Linux (apt/yum) : /var/log/mongodb/mongod.log
macOS (Homebrew) : /usr/local/var/log/mongodb/mongo.log
Docker : les journaux sont souvent envoyés vers stdout, mais il peut être configuré pour écrire dans /var/log/mongodb/mongod.log

Si MongoDB envoie ses journaux vers stdout, configurez-le pour qu’il les écrive dans un fichier en mettant à jour mongod.conf :

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

Après avoir modifié la configuration, redémarrez MongoDB :

# For systemd
sudo systemctl restart mongod

# For Docker
docker restart <mongodb-container>

Créer une configuration personnalisée de l’OTel collector pour MongoDB

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement. La configuration personnalisée est fusionnée avec la configuration de base gérée par HyperDX via OpAMP.

Créez un fichier nommé mongodb-monitoring.yaml avec la configuration suivante :

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

Configurer ClickStack pour charger une configuration personnalisée

Pour activer une configuration personnalisée du collecteur dans votre déploiement ClickStack existant, vous devez :

Monter le fichier de configuration personnalisé à l’emplacement /etc/otelcol-contrib/custom.config.yaml
Définir la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Monter le répertoire des journaux MongoDB afin que le collecteur puisse les lire

Mettez à jour la configuration de votre déploiement ClickStack :

services:
  clickstack:
    # ... configuration existante ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... autres variables d’environnement ...
    volumes:
      - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mongodb:/var/log/mongodb:ro
      # ... autres volumes ...

Si vous utilisez l’image tout-en-un avec Docker, exécutez :

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

Vérifier les logs dans HyperDX

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les logs arrivent bien :

Jeu de données de démonstration

Testez l’intégration MongoDB avec un jeu de données d’exemple pré-généré avant de configurer vos systèmes de production.

Télécharger le jeu de données d’exemple

Téléchargez le fichier de logs d’exemple :

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

Créer une configuration de collector de test

Créez un fichier nommé mongodb-demo.yaml avec la configuration suivante :

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

Exécuter ClickStack avec la configuration de démonstration

Exécutez ClickStack avec les logs et la configuration de démonstration :

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

Vérifier les logs dans HyperDX

Une fois ClickStack lancé :

Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
Accédez à la vue Search et définissez la source sur Logs
Définissez l’intervalle de temps de manière à inclure 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

Tableaux de bord et visualisation

Télécharger la configuration du tableau de bord

Télécharger le fichier de configuration du tableau de bord.

Importer un tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section tableaux de bord.
Cliquez sur "Import Dashboard" dans l’angle supérieur droit, dans le menu à trois points.

Téléversez le fichier mongodb-logs-dashboard.json, puis cliquez sur "Finish import".

Terminer l’importation du tableau de bord des logs MongoDB

Le tableau de bord sera créé avec toutes les visualisations préconfigurées

Pour le jeu de données de démonstration, définissez l’intervalle de temps de manière à inclure 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

Dépannage

Aucun log ne s’affiche dans HyperDX

Vérifiez que la configuration effective inclut votre filelog receiver :

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

Vérifiez les logs du collector à la recherche d’erreurs :

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

Les logs ne sont pas correctement analysés

Vérifiez que MongoDB génère des logs au format JSON (4.4+) :

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

Si la sortie n’est pas un JSON valide, il se peut que votre version de MongoDB utilise l’ancien format de journalisation en texte brut (antérieur à la version 4.4). Vous devrez remplacer l’opérateur json_parser par regex_parser, ou passer à MongoDB 4.4+.

Étapes suivantes

Configurez des alertes pour les événements critiques (pics d’erreurs, seuils de requêtes lentes)
Créez des tableaux de bord supplémentaires pour des cas d’utilisation spécifiques (surveillance d’un Replica Set, suivi des connexions)

Passage en production

Ce guide s’appuie sur l’OpenTelemetry Collector intégré à ClickStack pour une mise en place rapide. Pour les déploiements en production, nous vous recommandons de déployer votre propre OTel Collector et d’envoyer les données vers l’endpoint OTLP de ClickStack. Consultez Envoi de données OpenTelemetry pour la configuration de production.