Journalisation & Débogage

La journalisation fiable est l'un des composants principaux de l'architecture du Bot de Trading ByNinja. Chaque action importante dans le système est enregistrée, structurée et transférée en temps réel via l'intégration Telegram. Cela permet aux traders de surveiller le bot à distance, de détecter les problèmes instantanément et de déboguer des scénarios de trading complexes sans accès direct au serveur.

Le système de journalisation est conçu autour de trois objectifs principaux :

•Surveillance en temps réel
•Diagnostics d'erreur détaillés
•Observabilité à distance via Telegram

Contrairement aux implémentations basiques limitées à la console, l'infrastructure ByNinja combine des fichiers journaux rotatifs, une sortie console, un transfert TCP et une livraison Telegram dans un pipeline de surveillance unifié.

Structure des Journaux

Le bot utilise une architecture de journalisation centralisée construite sur le module logging de Python.

Chaque message de journal suit une structure standardisée :

Code

2026-05-19 14:32:11 - TradingBot - INFO - Opened BUY position BTCUSDT

Le formateur inclut :

•Horodatage
•Nom du logger
•Niveau de gravité
•Message lisible par un humain

Exemple de configuration du formateur :

Code

&#039;%(asctime)s - %(name)s - %(levelname)s - %(message)s&#039;

Cette structure rend les journaux faciles à :

•Rechercher
•Analyser
•Filtrer
•Analyser
•Transférer vers des systèmes externes

Le système utilise plusieurs niveaux de journalisation :

Niveau	Objectif
DEBUG	Flux d'exécution interne
INFO	Actions de trading et mises à jour de statut
WARNING	Comportement suspect ou inattendu
ERROR	Pannes récupérables
CRITICAL	Problèmes système fatals

Fichiers Journaux Rotatifs

Le logger stocke automatiquement les journaux dans des fichiers rotatifs en utilisant RotatingFileHandler.

Les fonctionnalités incluent :

•Persistance automatique des journaux
•Limites de taille de fichier
•Sauvegardes historiques
•Support de l'encodage UTF-8

Configuration :

Code

RotatingFileHandler(
    filename=self._log_file,
    maxBytes=250*1024*1024,
    backupCount=5,
    encoding=&#039;utf-8&#039;
)

Cela empêche une croissance incontrôlée des journaux tout en préservant les données de débogage historiques.

Le système conserve :

•Journal actif en cours
•Jusqu'à 5 fichiers journaux archivés
•250 Mo par fichier

Cette approche est particulièrement importante pour les systèmes de trading fonctionnant en continu 24h/24 et 7j/7.

Journalisation Telegram en Temps Réel

L'une des caractéristiques clés de l'infrastructure ByNinja est que les journaux du bot de trading sont automatiquement transférés vers le bot Telegram en temps réel.

L'architecture fonctionne comme suit :

Code

Trading Bot
    ↓
Python Logger
    ↓
TCP Log Handler
    ↓
TCP Client
    ↓
Telegram TCP Server
    ↓
Telegram Bot
    ↓
Telegram Chat

Chaque événement important généré par le bot de trading peut instantanément apparaître dans le canal ou le chat Telegram privé.

Exemples :

Code

✅ Position opened
📈 Take profit executed
⚠️ API rate limit warning
❌ Binance order rejected
🛑 Emergency shutdown triggered

Cela donne à l'opérateur une visibilité immédiate sur le système sans accès SSH ni outils de surveillance de serveur.

Le mécanisme de transfert est implémenté via un gestionnaire de journalisation TCP personnalisé :

Code

tcp_handler = TCPLogHandler(tcp_manager)
logger.addHandler(tcp_handler)

Le serveur Telegram reçoit les messages via TCP et les transfère directement à l’API Telegram Bot.

Cela transforme efficacement Telegram en un tableau de bord de surveillance à distance en temps réel pour le moteur de trading.

Flux de Travail de Débogage

Le flux de travail de débogage est conçu pour une isolation et une récupération rapides des problèmes.

Étape 1 — Détecter le Problème

La plupart des problèmes sont immédiatement visibles via les notifications Telegram.

Exemple :

Code

❌ Error starting TCP client: Connection refused

ou :

Code

⚠️ Unknown message type

Comme les journaux sont livrés en temps réel, les problèmes peuvent souvent être détectés en quelques secondes.

Étape 2 — Inspecter les Journaux Détaillés

Lorsqu’une enquête plus approfondie est nécessaire, les développeurs peuvent inspecter :

•trading.log
•telegram_tcp.log
•trading_tcp.log

Les journaux fournissent des traces d'exécution chronologiques pour :

•Décisions de stratégie
•Exécution des ordres
•Communication TCP
•Interactions Telegram
•Opérations de persistance
•Événements d'arrêt

Étape 3 — Reproduire le Scénario

Le niveau DEBUG peut être activé pour capturer :

•Transitions d’état internes
•Flux de messages TCP
•Exécution des commandes
•Cycle de vie des threads
•Opérations de persistance

Cela permet aux développeurs de reproduire des cas limites difficiles et des conditions de concurrence.

Étape 4 — Tracer la Chaîne de Défaillance

Parce que chaque sous-système utilise une journalisation centralisée, il devient possible de reconstruire la séquence exacte des événements ayant conduit à une défaillance.

Exemple de chaîne :

Code

Signal generated
→ Order request sent
→ Binance API timeout
→ Retry triggered
→ Risk manager warning
→ Position recovery activated

Ceci est particulièrement utile dans les systèmes asynchrones multi-threads où les problèmes peuvent provenir loin du point de défaillance visible.

Traçage des Erreurs

Le système de journalisation est fortement axé sur le traçage structuré des erreurs.

Toutes les opérations critiques sont encapsulées dans des blocs try/except avec un rapport d’erreur explicite :

Code

except Exception as e:
    logger.error(f"❌ Critical error: {e}")

Cela garantit que les défaillances inattendues ne disparaissent jamais silencieusement.

Le système trace les erreurs à travers plusieurs couches :

Couche	Exemples d’Erreurs
API Binance	Rejet de ordre, timeout
Couche TCP	Perte de connexion
Bot Telegram	Défaillances de l'API
Persistance	Corruption de fichier
Moteur de Stratégie	Signaux invalides
Threading	Interblocages ou crashes

Conseil Pro : Utilisez un Éditeur de Code

Pour une bien meilleure expérience de modification des fichiers de configuration, nous vous recommandons d’utiliser un éditeur de code professionnel comme Visual Studio Code.

Download VS Code ↗

Journalisation de l'Arrêt Gracieux

Le bot journalise également les opérations d’arrêt et de récupération.

Exemple :

Code

🛑 Shutdown signal received...
✅ PersistentMap stopped
💾 Forcing save to disk...

Ceci est extrêmement important dans les environnements de trading car cela confirme que :

•Les positions ont été sauvegardées
•Les threads se sont arrêtés correctement
•Les opérations en attente sont terminées
•La persistance a été vidée avec succès

Opérations à Distance via Telegram

L'intégration Telegram ne se limite pas aux journaux passifs.

La même infrastructure prend également en charge l’exécution de commandes à distance.

Exemples :

Code

/starttrading
/stoptrading
/getstatus
/getstats
/buy BTCUSDT
/sell ETHUSDT

Cela crée un flux de travail opérationnel entièrement à distance :

•Recevoir des alertes dans Telegram
•Analyser les journaux
•Envoyer des commandes de récupération
•Surveiller les résultats d'exécution

Le tout sans accès direct au serveur.

Architecture de Surveillance Orientée Production

L'architecture globale de journalisation combine plusieurs pratiques de qualité production :

•Journalisation centralisée
•Formatage structuré
•Fichiers journaux rotatifs
•Notifications à distance en temps réel
•Journalisation multi-thread sûre
•Streaming de journaux TCP
•Traçage de l'arrêt gracieux
•Contrôle opérationnel à distance

Cela transforme le sous-système de journalisation d’un simple utilitaire de débogage en une infrastructure complète de surveillance et d’exploitation pour le trading crypto automatisé.