Logging & Debugging

Il logging affidabile è uno dei componenti centrali dell'architettura del Trading Bot ByNinja. Ogni azione importante all'interno del sistema viene registrata, strutturata e inoltrata in tempo reale attraverso l'integrazione Telegram. Questo permette ai trader di monitorare il bot a distanza, rilevare problemi istantaneamente e eseguire il debug di scenari di trading complessi senza accesso diretto al server.

Il sistema di logging è progettato attorno a tre obiettivi principali:

•Monitoraggio in tempo reale
•Diagnostica dettagliata degli errori
•Osservabilità remota tramite Telegram

A differenza delle implementazioni di base basate solo sulla console, l'infrastruttura ByNinja combina file di log rotanti, output console, inoltro TCP e consegna Telegram in una pipeline di monitoraggio unificata.

Struttura dei Log

Il bot utilizza un'architettura di logging centralizzata costruita sul modulo logging di Python.

Ogni messaggio di log segue una struttura standardizzata:

Code

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

Il formatter include:

•Timestamp
•Nome logger
•Livello di gravità
•Messaggio leggibile

Esempio di configurazione formatter:

Code

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

Questa struttura rende i log facili da:

•Cercare
•Analizzare
•Filtrare
•Analizzare
•Inoltrare a sistemi esterni

Il sistema utilizza molteplici livelli di logging:

Livello	Scopo
DEBUG	Flusso di esecuzione interno
INFO	Azioni di trading e aggiornamenti di stato
WARNING	Comportamento sospetto o inaspettato
ERROR	Guasti recuperabili
CRITICAL	Problemi di sistema fatali

File di Log Rotanti

Il logger memorizza automaticamente i log in file rotanti utilizzando RotatingFileHandler.

Le caratteristiche includono:

•Persistenza automatica dei log
•Limiti di dimensione file
•Backup storici
•Supporto codifica UTF-8

Configurazione:

Code

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

Questo previene la crescita incontrollata dei log preservando i dati di debug storici.

Il sistema conserva:

•Log attivo corrente
•Fino a 5 file di log archiviati
•250 MB per file

Questo approccio è particolarmente importante per sistemi di trading a lungo termine che operano ininterrottamente 24/7.

Logging Telegram in Tempo Reale

Una delle caratteristiche chiave dell'infrastruttura ByNinja è che i log del bot di trading vengono automaticamente inoltrati al bot Telegram in tempo reale.

L'architettura funziona in questo modo:

Code

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

Ogni evento importante generato dal bot di trading può apparire istantaneamente all'interno del canale o chat Telegram privata.

Esempi:

Code

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

Questo dà all'operatore visibilità immediata sul sistema senza accesso SSH o strumenti di monitoraggio del server.

Il meccanismo di inoltro è implementato attraverso un handler di logging TCP personalizzato:

Code

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

Il server Telegram riceve i messaggi tramite TCP e li inoltra direttamente all'API del Bot Telegram.

Questo trasforma efficacemente Telegram in un dashboard di monitoraggio remoto in tempo reale per il motore di trading.

Flusso di Lavoro Debug

Il flusso di lavoro di debug è progettato per un rapido isolamento dei problemi e recupero.

Passo 1 — Rilevare il Problema

La maggior parte dei problemi è immediatamente visibile attraverso le notifiche Telegram.

Esempio:

Code

❌ Error starting TCP client: Connection refused

oppure:

Code

⚠️ Unknown message type

Poiché i log vengono consegnati in tempo reale, i problemi possono spesso essere rilevati entro secondi.

Passo 2 — Ispezionare i Log Dettagliati

Quando è richiesta un'indagine più approfondita, gli sviluppatori possono ispezionare:

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

I log forniscono tracce di esecuzione cronologiche per:

•Decisioni della strategia
•Esecuzione dell'ordine
•Comunicazione TCP
•Interazioni Telegram
•Operazioni di persistenza
•Eventi di spegnimento

Passo 3 — Riprodurre lo Scenario

Il livello DEBUG può essere abilitato per catturare:

•Transizioni di stato interne
•Flusso di messaggi TCP
•Esecuzione dei comandi
•Ciclo di vita dei thread
•Operazioni di persistenza

Questo permette agli sviluppatori di riprodurre casi limite difficili e race condition.

Passo 4 — Tracciare la Catena del Guasto

Poiché ogni sottosistema utilizza il logging centralizzato, diventa possibile ricostruire l'esatta sequenza di eventi che portano a un guasto.

Catena di esempio:

Code

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

Questo è particolarmente utile in sistemi multi-thread asincroni dove i problemi possono originare lontano dal punto di guasto visibile.

Tracciamento Errori

Il sistema di logging è fortemente focalizzato sul tracciamento strutturato degli errori.

Tutte le operazioni critiche sono racchiuse in blocchi try/except con reporting esplicito degli errori:

Code

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

Questo garantisce che i guasti imprevisti non scompaiano mai silenziosamente.

Il sistema traccia gli errori attraverso molteplici livelli:

Livello	Errori Esempio
API Binance	Rifiuto ordine, timeout
Livello TCP	Perdita connessione
Bot Telegram	Guasti API
Persistenza	Corruzione file
Motore Strategia	Segnali non validi
Threading	Deadlock o crash

Consiglio Pro: Usa un Editor di Codice

Per un'esperienza molto migliore durante la modifica dei file di configurazione, raccomandiamo di utilizzare un editor di codice professionale come Visual Studio Code.

Download VS Code ↗

Logging Spegnimento Graduale

Il bot registra anche le operazioni di spegnimento e recupero.

Esempio:

Code

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

Questo è estremamente importante negli ambienti di trading perché conferma che:

•Le posizioni sono state salvate
•I thread si sono fermati correttamente
•Le operazioni in sospeso sono state completate
•La persistenza è stata scaricata con successo

Operazioni Remote Tramite Telegram

L'integrazione Telegram non è limitata ai log passivi.

La stessa infrastruttura supporta anche l'esecuzione di comandi remoti.

Esempi:

Code

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

Questo crea un flusso di lavoro operativo completamente remoto:

•Ricevi avvisi in Telegram
•Analizza i log
•Invia comandi di recupero
•Monitora i risultati dell'esecuzione

Tutto senza accesso diretto al server.

Architettura di Monitoraggio Orientata alla Produzione

L'architettura di logging complessiva combina diverse pratiche di livello produttivo:

•Logging centralizzato
•Formattazione strutturata
•File di log rotanti
•Notifiche remote in tempo reale
•Logging multi-thread-safe
•Streaming log TCP
•Tracciamento spegnimento graduale
•Controllo operativo remoto

Questo trasforma il sottosistema di logging da un semplice strumento di debug in un'infrastruttura di monitoraggio e operativa completa per il trading crypto automatizzato.