Dépannage MongoDB avec exemples pratiques : guide d’implémentation pas à pas

Intro

MongoDB est résilient, mais la production rencontre parfois des accrocs : service qui ne démarre pas, connexions qui expirent, requêtes qui se traînent, ou répliques qui dérivent. Ce guide propose un playbook pas à pas et éprouvé : que vérifier en premier, quelles commandes sûres exécuter, comment interpréter les sorties, quand escalader, et comment revenir en arrière sans effets secondaires inattendus. L’accent est mis sur des diagnostics rapides et répétables, et des changements réversibles que vous pouvez valider en quelques minutes.

L’approche :

• Dresser l’inventaire de l’environnement pour éviter de poursuivre une mauvaise piste.
• Collecter journaux et métriques avant tout changement.
• Appliquer le plus petit correctif sûr, vérifier, puis seulement poursuivre.
• Prévoir un plan de retour arrière pour chaque action.

Inventaire des versions et de l’environnement

De petits détails de version ou de topologie expliquent souvent les symptômes. Capturez-les une fois par environnement et gardez-les sous la main pendant les incidents.

• Bases serveur et stockage
• Version binaire (sur l’hôte) :

    mongod --version

• Infos de build et version (via le shell) :

    mongosh --eval 'db.serverBuildInfo().version'

• Moteur de stockage :

    mongosh --eval 'db.serverStatus().storageEngine'

• Version de compatibilité des fonctionnalités (FCV) :

    mongosh admin --eval 'db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })'

• Topologie
• État du replica set :

    mongosh --eval 'rs.status()'

• Vue d’ensemble d’un cluster shardé :

    mongosh --eval 'sh.status()'

• Journaux et contrôle du service
• État du service (systemd) :

    sudo systemctl status mongod

• Journaux récents (dernière heure) :

    sudo journalctl -u mongod -S -1h

• Fichiers de logs (chemins typiques) :
• Linux : /var/log/mongodb/mongod.log
• Windows : C:\\Program Files\\MongoDB\\Server\\7.0\\log\\mongod.log
• Détails du pilote et de l’app (exemple Node.js)
• Version du pilote :

    npm ls mongodb

• Exemple de chaîne de connexion :

    mongodb+srv://appuser:[email protected]/appdb?retryWrites=true&maxPoolSize=50&serverSelectionTimeoutMS=5000

• Tout changement récent des paramètres de pooling (Mongoose ou pilote natif).
• Vérifications rapides de l’hôte
• Espace disque :

    df -h

• CPU et mémoire :

    top

• Descripteurs de fichiers (Linux) :

    ulimit -n

Paramètres sûrs par défaut pendant la phase de triage

Privilégiez des actions réversibles et à faible risque pendant le diagnostic :

• Write concern : utilisez w: "majority" pour les écritures critiques lors des vérifications de cohérence (validez d’abord les attentes de l’app).
• Préférence de lecture pour les tableaux de bord non critiques : primaryPreferred pour encaisser de brèves élections; gardez les lectures critiques sur le primaire quand la cohérence prime.
• Évitez les changements globaux côté serveur. Préférez des options au niveau de la session ou de la commande.
• Ajustez les timeouts du pilote (par exemple serverSelectionTimeoutMS=5000) plutôt que ceux du serveur pour isoler des problèmes DNS ou réseau.
• Pour de nouveaux index sur un replica set, procédez en rolling : construisez d’abord sur les secondaires, puis sur le primaire, en surveillant la latence de réplication.
• N’exécutez pas --repair sauf si vous avez validé des sauvegardes et compris les compromis. Préférez une restauration ou une resynchronisation.

Vérifications et diagnostics (avant tout changement)

• Le serveur est-il en marche et accessible ?
• Service :

    sudo systemctl is-active --quiet mongod && echo RUNNING || echo STOPPED

• Port ouvert :

    ss -ltnp | grep :27017
    # Windows : netstat -ano | findstr 27017

• Depuis l’hôte applicatif, test de ping :

    mongosh 'mongodb://hostA:27017/admin?serverSelectionTimeoutMS=3000' --eval 'db.runCommand({ ping: 1 })'

Attendu : la sortie contient { ok: 1 }.

• Que disent les journaux ?
• 200 dernières lignes :

    sudo tail -n 200 /var/log/mongodb/mongod.log

• Chercher : échecs d’authentification, erreurs WiredTiger (WT), élections, tempêtes de connexions, requêtes lentes, messages disque plein.

• Pression sur les connexions

  mongosh --eval 'db.serverStatus().connections'

Sain sous charge modérée : current doit être nettement en dessous de available. Si current approche available, les timeouts sont probables.

• Santé de la réplication (replica sets)

  mongosh --eval 'rs.status()'
  mongosh --eval 'rs.printSecondaryReplicationInfo()'

Attendu : les membres montrent PRIMARY ou SECONDARY, avec un faible retard (secondes) en régime stable.

• Opérations lentes et verrous
• Opérations en cours en attente de verrous :

    mongosh --eval '
    db.aggregate([
      { $currentOp: { allUsers: true, idleConnections: false } },
      { $match: { op: { $in: ["query","insert","update","delete","getmore"] }, waitingForLock: true } },
      { $project: { op:1, ns:1, secs_running:1, waitingForLock:1, client:1, msg:1 } }
    ]).toArray()'

• Accès index par collection :

    mongosh appdb --eval '
    db.orders.aggregate([
      { $indexStats: {} },
      { $project: { name:1, accesses: "$accesses.ops", since: "$accesses.since" } }
    ]).toArray()'

• Disque et cache
• Espace disque (gardez 10–20 % libres) :

    df -h

• Cache WiredTiger :

    mongosh --eval 'db.serverStatus().wiredTiger.cache'

Surveillez une utilisation élevée proche du maximum configuré et des évictions fréquentes corrélées à des requêtes lentes.

Carte rapide des symptômes (quoi vérifier en premier)

• L’app affiche ECONNREFUSED : mongod arrêté ou port bloqué. Vérifiez systemctl status mongod et ss -ltnp | grep 27017.
• Échec d’authentification : mauvaise base ou authSource incorrect. Essayez mongosh --authenticationDatabase admin -u appuser -p ....
• Requêtes lentes et CPU élevé : index manquant probable. Exécutez explain('executionStats') pour la requête.
• Latence de réplication qui augmente : secondaire lent ou réseau. Vérifiez rs.printSecondaryReplicationInfo().
• Alertes disque plein : logs qui gonflent ou fichiers temporaires. Vérifiez df -h, faites une rotation des logs et nettoyez les répertoires temporaires sûrs.

Modes de panne et rétablissement

Exécutez une étape de vérification après chaque changement. Arrêtez-vous si le système se stabilise.

1) Le serveur ne démarre pas

Journaux typiques : port déjà utilisé, erreurs de permissions, ou erreurs de métadonnées WiredTiger.

• Confirmer service et journaux

  sudo systemctl status mongod
  sudo journalctl -u mongod -n 200

• Conflit de port : trouver et arrêter en sécurité le processus en conflit

  ss -ltnp | grep :27017
  sudo fuser -k 27017/tcp

• Permissions du chemin de données (Linux par défaut)

  sudo chown -R mongodb:mongodb /var/lib/mongo
  sudo chmod 700 /var/lib/mongo

• Erreurs de métadonnées WiredTiger (par exemple, messages concernant WiredTiger.turtle)
• Récupération la plus sûre : restaurer depuis une sauvegarde valide ou réensemencer depuis une réplique saine.
• Dernier recours sur un standalone :

    sudo systemctl stop mongod
    sudo cp -a /var/lib/mongo /var/lib/mongo.backup
    sudo -u mongodb mongod --dbpath /var/lib/mongo --repair
    sudo systemctl start mongod

• Vérifier :

  mongosh --eval 'db.adminCommand({ ping: 1 })'

2) Échecs d’authentification

Symptômes : « Authentication failed » répété; utilisateurs manquants; authSource erroné.

• Confirmer la base qui possède l’utilisateur (souvent admin) :

  mongosh 'mongodb://appuser:S3cretP4ss!@hostA/admin' --eval 'db.runCommand({ connectionStatus: 1 })'

• Lister les utilisateurs (portée admin) :

  mongosh admin -u clusterAdmin -p 'AdminP@ssw0rd!' --eval 'db.getUsers()'

• Si l’utilisateur manque, créer l’utilisateur au moindre privilège :

  mongosh admin -u clusterAdmin -p 'AdminP@ssw0rd!' --eval '
  db.createUser({ user: "appuser", pwd: "S3cretP4ss!", roles: [{ role: "readWrite", db: "appdb" }] })'

• Si authSource est incorrect, corriger l’URI :

  mongodb://appuser:S3cretP4ss!@hostA,hostB/appdb?replicaSet=rs0&authSource=admin

• Vérifier avec un test lecture/écriture sur appdb. Rétrograder tout rôle temporaire après le triage.

3) Épuisement du pool de connexions (Node.js/Express)

Symptômes : MongoNetworkTimeout, timeouts sous charge, messages fréquents « connection pool cleared ».

• Vérifier la pression :

  mongosh --eval 'db.serverStatus().connections'

• Si les clients ouvrent/ferment sans cesse, dimensionnez correctement et réutilisez un seul client par processus :

  const { MongoClient } = require('mongodb');
  const client = new MongoClient('mongodb+srv://appuser:[email protected]/appdb', {
    maxPoolSize: 50,
    minPoolSize: 5,
    waitQueueTimeoutMS: 2000,
    serverSelectionTimeoutMS: 5000,
    retryWrites: true
  });
  module.exports = client; // réutiliser cette instance dans toute l’app

• Assurez-vous que le DNS est stable et que les enregistrements SRV sont à jour. Activez HTTP keep-alive sur votre couche API pour éviter de nouvelles connexions par requête.
• Vérifier : les timeouts diminuent, serverStatus().connections se stabilise. Rétablissez les tailles de pool si la contention s’aggrave.

4) Requêtes lentes et index manquants

Symptômes : CPU élevé, lectures lentes, scans de collection fréquents.

• Obtenir un plan d’exécution :

  mongosh appdb --eval "db.orders.find({ customerId: 12345, status: 'OPEN' }).explain('executionStats')"

Signes d’alerte : COLLSCAN, totalDocsExamined élevé, executionTimeMillis important.

• Inspecter les index :

  mongosh appdb --eval 'db.orders.getIndexes()'

• Créer un index ciblé qui correspond à la forme de la requête :

  mongosh appdb --eval 'db.orders.createIndex({ customerId: 1, status: 1 })'

• Relancer l’explain; attendre IXSCAN avec bien moins de documents examinés. Si la charge en écriture augmente trop, revenir en arrière :

  mongosh appdb --eval 'db.orders.dropIndex({ customerId: 1, status: 1 })'

• Dans un replica set, réduire l’impact en construisant d’abord sur un secondaire, puis sur le primaire, en surveillant la latence de réplication.

5) Latence de réplication et rollbacks

Symptômes : les secondaires prennent du retard; les lectures depuis les secondaires sont obsolètes; rollbacks après bascule.

• Identifier le membre en retard et l’ampleur du décalage :

  mongosh --eval 'rs.printSecondaryReplicationInfo()'
  mongosh --eval 'rs.status()'

• Vérifier la latence réseau et l’I/O disque sur le nœud en retard. Réduire temporairement la pression d’écriture ou brider les batchs.
• Si un membre est très en retard, le resynchroniser :

  sudo systemctl stop mongod
  sudo cp -a /var/lib/mongo /var/lib/mongo.before-resync
  sudo rm -rf /var/lib/mongo/*
  sudo systemctl start mongod
  # Le membre effectue une initial sync depuis le primaire

• Pour les rollbacks après perte soudaine du primaire, inspecter les fichiers de rollback sur le nœud affecté et réconcilier au niveau applicatif.
• Vérifier : la latence baisse régulièrement; rs.status() montre des états sains. Si la resync est longue, gardez temporairement le nœud sans droit de vote pour protéger la disponibilité.

6) Disque plein, journal et logs

Symptômes : écritures en échec; logs avec « No space left on device »; throttling WiredTiger.

• Vérifier l’espace (et les inodes sous Linux) :

  df -h
  df -i
  sudo du -sh /var/log/mongodb

• Ordre de rétablissement :

1. Faire une rotation et compresser les logs en sécurité :

     sudo logrotate -f /etc/logrotate.d/mongod

1. Nettoyer d’anciens fichiers de diagnostic ou temporaires dans les répertoires applicatifs (ne jamais retirer de fichiers du dbPath de MongoDB).
2. Ajouter de la capacité disque ou migrer le dbPath vers un volume plus grand lors d’une maintenance planifiée (arrêt propre, mise à jour de la config, redémarrage propre).

• Vérifier : restaurer au moins 10–20 % d’espace libre; confirmer que les nouvelles écritures réussissent.

7) Construction d’index unique bloquée par des doublons

Symptômes : E11000 duplicate key error lors de la création d’un index unique.

• Trouver les doublons sur { email: 1 } :

  mongosh appdb --eval '
  const dupes = db.users.aggregate([
    { $group: { _id: "$email", c: { $sum: 1 }, ids: { $push: "$_id" } } },
    { $match: { c: { $gt: 1 } } },
    { $limit: 20 }
  ]).toArray();
  printjson(dupes);
  '

• Résoudre les doublons : fusionner, supprimer ou réattribuer selon les règles de l’application.
• Créer l’index unique une fois propre :

  mongosh appdb --eval 'db.users.createIndex({ email: 1 }, { unique: true })'

• Vérifier : l’index existe; les nouvelles écritures respectent l’unicité. Si des flux historiques cassent, supprimez l’index et planifiez une migration progressive.

Liste de contrôle des opérations (rapide et sûre)

• Inventorier versions, topologie et faits d’environnement.
• Vérifier l’état du service, le port et un ping basique.
• Lire les 200 dernières lignes de log.
• Vérifier les connexions et les opérations lentes.
• Valider la réplication et l’espace disque.
• Appliquer le plus petit correctif sûr.
• Revérifier et documenter ce qui a changé et pourquoi.

Commandes pratiques que vous pouvez exécuter sans risque

• Ping santé rapide :

  mongosh --eval 'db.runCommand({ ping: 1 })'

• Résumé des connexions :

  mongosh --eval 'db.serverStatus().connections'

• Identifier le plan d’une requête lente :

  mongosh appdb --eval "db.orders.find({ status: 'OPEN' }).sort({ createdAt: -1 }).limit(10).explain('executionStats')"

• Résumé de la latence de réplication :

  mongosh --eval 'rs.printSecondaryReplicationInfo()'

• Afficher les index d’une collection chaude :

  mongosh appdb --eval 'db.orders.getIndexes()'

Résultats attendus et comment les interpréter

• Ping retourne { ok: 1 } : serveur joignable; si l’app échoue encore, concentrez-vous sur DNS, TLS ou l’authentification.
• Connexions : si current frôle available, ajustez les pools côté client et réduisez le turn-over des connexions.
• Plan d’exécution : privilégiez IXSCAN avec peu de documents examinés; COLLSCAN suggère un index manquant ou inadéquat.
• Réplication : des retards en minutes ou heures nécessitent une action. Vérifiez disque et réseau sur les membres en retard.
• Cache WiredTiger : une utilisation soutenue proche du maximum avec évictions et requêtes lentes indique une pression mémoire ou des index inadaptés.

Vérification après échec et retour arrière

Chaque correctif ci-dessus inclut une étape de vérification. Si le système ne s’améliore pas, revenez immédiatement en arrière et recueillez plus d’éléments.

• Réglages du pilote : revenez aux tailles de pool ou timeouts connus comme stables.
• Changements d’index : supprimez les index ajoutés si ils dégradent les écritures; envisagez des index composés plus sélectifs.
• Actions de resync ou stepdown : rétablissez l’état précédent des membres si le comportement d’élection nuit à la disponibilité.
• Réparation de stockage : si les réparations introduisent de la divergence, restaurez une sauvegarde ou réensemencez depuis une réplique saine.

Conclusion

Un dépannage MongoDB efficace est structuré, observable et réversible. Commencez par confirmer versions et topologie, lisez les journaux les plus récents et exécutez quelques commandes d’état à fort signal. Appliquez le plus petit correctif sûr, vérifiez, puis seulement poursuivez. Les parcours proposés ici aident à résoudre les pannes les plus courantes — démarrage, authentification, requêtes lentes, pression sur le pool de connexions, latence de réplication et capacité disque — tout en limitant le risque et en préservant un chemin de retour clair. Adoptez ce flux d’abord sur un service, validez les résultats, puis standardisez-le à travers vos environnements pour une réponse aux incidents plus rapide et plus sûre.