Registo (Logging) e Depuração (Debugging)

O registo (logging) confiável é um dos componentes principais da arquitetura do Bot de Trading ByNinja. Cada ação importante dentro do sistema é registada, estruturada e encaminhada em tempo real através da integração com o Telegram. Isto permite que os traders monitorizem o bot remotamente, detetem problemas instantaneamente e depurem cenários de trading complexos sem acesso direto ao servidor.

O sistema de logging é projetado em torno de três objetivos principais:

•Monitorização em tempo real
•Diagnóstico detalhado de erros
•Observabilidade remota através do Telegram

Ao contrário de implementações básicas apenas com consola, a infraestrutura ByNinja combina ficheiros de log rotativos, saída para consola, encaminhamento TCP e entrega pelo Telegram num pipeline de monitorização unificado.

Estrutura do Log

O bot usa uma arquitetura de logging centralizada construída sobre o módulo de logging do Python.

Cada mensagem de log segue uma estrutura padronizada:

Code

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

O formatador inclui:

•Timestamp
•Nome do logger
•Nível de gravidade
•Mensagem legível por humanos

Exemplo de configuração do formatador:

Code

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

Esta estrutura torna os logs fáceis de:

•Pesquisar
•Analisar (parse)
•Filtrar
•Analisar (analyze)
•Encaminhar para sistemas externos

O sistema usa múltiplos níveis de logging:

Nível	Objetivo
DEBUG	Fluxo de execução interna
INFO	Ações de trading e atualizações de estado
WARNING	Comportamento suspeito ou inesperado
ERROR	Falhas recuperáveis
CRITICAL	Problemas fatais do sistema

Ficheiros de Log Rotativos

O logger armazena automaticamente logs em ficheiros rotativos usando RotatingFileHandler.

As características incluem:

•Persistência automática de log
•Limites de tamanho de ficheiro
•Cópias de segurança históricas
•Suporte a codificação UTF-8

Configuração:

Code

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

Isso evita o crescimento descontrolado de logs enquanto preserva os dados históricos de depuração.

O sistema mantém:

•Log ativo atual
•Até 5 ficheiros de log arquivados
•250 MB por ficheiro

Esta abordagem é especialmente importante para sistemas de trading de longa duração que operam continuamente 24/7.

Registo (Logging) no Telegram em Tempo Real

Uma das principais características da infraestrutura ByNinja é que os logs do bot de trading são automaticamente encaminhados para o bot do Telegram em tempo real.

A arquitetura funciona assim:

Code

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

Cada evento importante gerado pelo bot de trading pode aparecer instantaneamente dentro do canal ou chat privado do Telegram.

Exemplos:

Code

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

Isto dá ao operador visibilidade imediata do sistema sem acesso SSH ou ferramentas de monitorização do servidor.

O mecanismo de encaminhamento é implementado através de um manipulador de logging TCP personalizado:

Code

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

O servidor Telegram recebe mensagens através de TCP e encaminha-as diretamente para a API do Bot Telegram.

Isso transforma efetivamente o Telegram num painel de monitorização remota em tempo real para o motor de trading.

Fluxo de Trabalho de Depuração

O fluxo de trabalho de depuração é projetado para rápida identificação e recuperação de problemas.

Passo 1 — Detetar o Problema

A maioria dos problemas é imediatamente visível através de notificações do Telegram.

Exemplo:

Code

❌ Error starting TCP client: Connection refused

ou:

Code

⚠️ Unknown message type

Como os logs são entregues em tempo real, os problemas podem frequentemente ser detetados em segundos.

Passo 2 — Inspecionar Logs Detalhados

Quando é necessária uma investigação mais profunda, os programadores podem inspecionar:

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

Os logs fornecem rastreios de execução cronológicos para:

•Decisões da estratégia
•Execução de ordens
•Comunicação TCP
•Interações com o Telegram
•Operações de persistência
•Eventos de encerramento

Passo 3 — Reproduzir o Cenário

O nível DEBUG pode ser ativado para capturar:

•Transições de estado interno
•Fluxo de mensagens TCP
•Execução de comandos
•Ciclo de vida das threads
•Operações de persistência

Isso permite que os programadores reproduzam casos extremos (edge cases) difíceis e condições de corrida (race conditions).

Passo 4 — Rastrear a Cadeia da Falha

Como cada subsistema usa logging centralizado, torna-se possível reconstruir a sequência exata de eventos que levam a uma falha.

Exemplo de cadeia:

Code

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

Isto é especialmente útil em sistemas multi-thread assíncronos onde os problemas podem originar-se longe do ponto de falha visível.

Rastreamento de Erros

O sistema de logging é muito focado no rastreamento estruturado de erros.

Todas as operações críticas estão envolvidas em blocos try/except com relatórios de erro explícitos:

Code

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

Isso garante que falhas inesperadas nunca desapareçam silenciosamente.

O sistema rastreia erros em múltiplas camadas:

Camada	Exemplos de Erros
API Binance	Rejeição de ordem, timeout
Camada TCP	Perda de conexão
Bot Telegram	Falhas de API
Persistência	Corrupção de ficheiro
Motor de Estratégia	Sinais inválidos
Threading	Deadlocks ou falhas (crashes)

Dica Profissional: Use um Editor de Código

Para uma experiência muito melhor ao editar ficheiros de configuração, recomendamos usar um editor de código profissional como o Visual Studio Code.

Download VS Code ↗

Registo de Encerramento Gracioso (Graceful Shutdown)

O bot também regista operações de encerramento e recuperação.

Exemplo:

Code

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

Isto é extremamente importante em ambientes de trading porque confirma que:

•Posições foram salvas
•Threads pararam corretamente
•Operações pendentes foram concluídas
•A persistência foi esvaziada com sucesso

Operações Remotas Através do Telegram

A integração com o Telegram não se limita a logs passivos.

A mesma infraestrutura também suporta a execução de comandos remotos.

Exemplos:

Code

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

Isto cria um fluxo de trabalho operacional totalmente remoto:

•Receber alertas no Telegram
•Analisar logs
•Enviar comandos de recuperação
•Monitorizar os resultados da execução

Tudo sem acesso direto ao servidor.

Arquitetura de Monitorização Orientada à Produção

A arquitetura de logging geral combina várias práticas de nível de produção:

•Registo (logging) centralizado
•Formatação estruturada
•Ficheiros de log rotativos
•Notificações remotas em tempo real
•Registo (logging) multi-thread seguro
•Transmissão de logs via TCP
•Rastreamento de encerramento gracioso
•Controlo operacional remoto

Isso transforma o subsistema de logging de uma simples utilidade de depuração numa infraestrutura completa de monitorização e operação para trading de criptomoedas automatizado.