Journalisation et débogage dans Dodock

Dodock offre plusieurs mécanismes pour suivre l'activité du système, diagnostiquer les problèmes et faciliter le débogage des applications. Cette page décrit les outils disponibles pour les administrateurs et développeurs.

1. Fichiers de log système

Dodock génère plusieurs fichiers de log dans le répertoire logs/ de votre installation. Ces fichiers enregistrent les événements système, les erreurs et les opérations critiques.

1.1 Principaux fichiers de log

1.2 Configuration de la journalisation

La journalisation dans Dodock est configurée via le fichier sites/common_site_config.json. Vous pouvez ajuster le niveau de log (DEBUG, INFO, WARNING, ERROR, CRITICAL) pour différents composants.

Exemple de configuration :

{
  "logging": [
    {
      "loggers": {
        "frappe": {
          "level": "INFO",
          "handlers": ["file", "console"]
        },
        "werkzeug": {
          "level": "DEBUG"
        }
      }
    }
  ]
}

2. Journalisation des imports de données

2.1 Suivi des échecs d'import

2.2 Types d'événements journalisés

2.3 Exemple de log d'échec d'import

ERROR:frappe.data_import:Row #12 failed in Client import: Value missing for required field: "Nom"
Traceback (most recent call last):
  File "apps/frappe/frappe/core/doctype/data_import/importer.py", line 312, in import_data
    doc = self.process_row(row)
  File "apps/frappe/frappe/core/doctype/data_import/importer.py", line 345, in process_row
    doc.insert()
  File "apps/frappe/frappe/model/document.py", line 285, in insert
    self._validate()
  File "apps/frappe/frappe/model/document.py", line 561, in _validate
    raise frappe.MandatoryError(f"Value missing for required field: {fieldname}")
frappe.exceptions.MandatoryError: Value missing for required field: "Nom"

2.4 Comment accéder aux logs d'import

1. Via les fichiers de log :
   • Consultez logs/frappe.log ou logs/worker.log selon le contexte d'exécution
   • Utilisez des outils comme grep pour filtrer les logs d'import :

     grep "data_import" logs/frappe.log
     

2. Via l'interface d'administration :
   • Allez dans Paramètres > Outils > Logs système
   • Filtrez par module "data_import"
3. Via la ligne de commande :

   bench --site [nom_du_site] show-log --module data_import --level ERROR
   

2.5 Bonnes pratiques pour le débogage des imports

1. Vérifiez les logs avant de relancer un import :
   • Les logs contiennent souvent des détails précis sur les erreurs (champ manquant, valeur invalide, etc.)
   • Utilisez ces informations pour corriger votre fichier d'import avant de relancer
2. Utilisez des imports par lots :
   • Pour les gros fichiers, divisez-les en lots plus petits (100-500 lignes)
   • Cela facilite l'identification des erreurs et réduit l'impact des échecs
3. Combinez avec les outils existants :
   • Les logs système complètent les informations disponibles dans :
     • Data Import Log (pour les erreurs de ligne)
     • Error Log (pour les échecs globaux)
     • Journal d'importation (dans le formulaire d'import)
4. Surveillez les imports en arrière-plan :
   • Les imports lancés via l'interface ou l'API peuvent s'exécuter en arrière-plan
   • Vérifiez régulièrement logs/worker.log pour suivre leur progression

      
flowchart TD
    A[Lancer un import de données] --> B{Import terminé ?}
    B -- Oui --> C[Vérifier le journal d'importation]
    B -- Non --> D[Consulter worker.log]
    C --> E{Erreurs détectées ?}
    E -- Oui --> F[Analyser frappe.log pour les détails]
    E -- Non --> G[Import réussi]
    F --> H[Corriger le fichier d'import]
    H --> A

    

3. Outils de débogage avancés

3.1 Mode débogage

Activez le mode débogage pour obtenir plus d'informations dans les logs :

bench --site [nom_du_site] set-config developer_mode 1
bench --site [nom_du_site] set-config debug 1

3.2 Journalisation personnalisée

Les développeurs peuvent ajouter des logs personnalisés dans leur code :

import frappe

# Journalisation basique
frappe.logger().info("Message d'information")

# Journalisation avec contexte
frappe.logger("data_import").error(
    f"Échec de l'import de la ligne {row.row_number}: {str(e)}",
    exc_info=True
)

3.3 Surveillance en temps réel

Pour surveiller les logs en temps réel :

# Sur le serveur
tail -f logs/frappe.log | grep -E "data_import|ERROR"

4. Résolution des problèmes courants

4.1 Import échoue sans message clair

1. Vérifiez frappe.log et worker.log pour les traces d'erreur
2. Activez le mode débogage si nécessaire
3. Vérifiez les permissions des fichiers et répertoires
4. Assurez-vous que le worker est en cours d'exécution :

   bench worker --status
   

4.2 Erreurs de mémoire lors d'imports volumineux

1. Divisez votre fichier en lots plus petits
2. Augmentez les ressources du serveur
3. Optimisez votre fichier CSV :
   • Supprimez les colonnes inutiles
   • Utilisez des valeurs simples (évitez les formules Excel)
   • Vérifiez l'encodage (UTF-8)

4.3 Problèmes de format de fichier

1. Vérifiez que votre fichier est bien au format CSV ou Excel
2. Pour les CSV :
   • Utilisez des virgules comme séparateurs
   • Encadrez les valeurs contenant des virgules avec des guillemets
   • Utilisez l'encodage UTF-8
3. Pour Excel :
   • Évitez les formules complexes
   • Vérifiez les formats de cellule (dates, nombres)

5. Intégration avec des outils externes

5.1 Export des logs vers des outils de monitoring

Dodock peut être configuré pour envoyer ses logs vers des outils externes comme :

• ELK Stack (Elasticsearch, Logstash, Kibana)
• Graylog
• Sentry (pour le suivi des erreurs)
• Datadog

Exemple de configuration pour Logstash :

{
  "logging": [
    {
      "loggers": {
        "frappe": {
          "handlers": ["file", "logstash"]
        }
      },
      "handlers": {
        "logstash": {
          "class": "logstash_async.handler.AsynchronousLogstashHandler",
          "host": "logstash.example.com",
          "port": 5044,
          "database_path": null
        }
      }
    }
  ]
}

5.2 Alertes sur erreurs critiques

Configurez des alertes pour être notifié des erreurs critiques dans les logs :

# Exemple avec fail2ban pour surveiller les erreurs d'import
[Definition]
failregex = ^.*ERROR.*data_import.*Row #.* failed.*$
ignoreregex =

6. Bonnes pratiques pour les développeurs

6.1 Journalisation efficace

1. Niveaux de log appropriés :
   • DEBUG : informations détaillées pour le débogage
   • INFO : événements normaux (import lancé, terminé)
   • WARNING : problèmes potentiels (import partiel)
   • ERROR : échecs nécessitant une intervention
   • CRITICAL : échecs critiques du système
2. Messages clairs :

   # Bon
   frappe.logger("data_import").error(f"Échec ligne {row.row_number}: champ 'Nom' manquant")
   
   # À éviter
   frappe.logger().error("Erreur d'import")
   

3. Contexte utile :
   • Incluez toujours le numéro de ligne pour les imports
   • Ajoutez des informations sur le document concerné
   • Utilisez exc_info=True pour les exceptions

6.2 Gestion des erreurs dans les imports

try:
    # Traitement de la ligne
    doc.insert()
except frappe.MandatoryError as e:
    frappe.logger("data_import").error(
        f"Ligne {row.row_number}: {str(e)}",
        exc_info=True
    )
    raise
except Exception as e:
    frappe.logger("data_import").error(
        f"Échec inattendu ligne {row.row_number}: {str(e)}",
        exc_info=True
    )
    raise

7. Références

• Documentation officielle Frappe sur la journalisation
• Guide de débogage Frappe
• Configuration avancée des logs