Registro y Depuración

El registro confiable (logging) es uno de los componentes centrales de la arquitectura del Bot de Trading ByNinja. Cada acción importante dentro del sistema se registra, estructura y reenvía en tiempo real a través de la integración con Telegram. Esto permite a los traders monitorear el bot de forma remota, detectar problemas al instante y depurar escenarios de trading complejos sin acceso directo al servidor.

El sistema de logging está diseñado en torno a tres objetivos principales:

•Monitoreo en tiempo real
•Diagnóstico detallado de errores
•Observabilidad remota a través de Telegram

A diferencia de las implementaciones básicas solo de consola, la infraestructura de ByNinja combina archivos de log rotativos, salida de consola, reenvío TCP y entrega por Telegram en una tubería de monitoreo unificada.

Estructura del Log

El bot utiliza una arquitectura de logging centralizada construida sobre el módulo logging de Python.

Cada mensaje de log sigue una estructura estandarizada:

Code

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

El formateador incluye:

•Marca de tiempo
•Nombre del logger
•Nivel de gravedad
•Mensaje legible por humanos

Ejemplo de configuración del formateador:

Code

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

Esta estructura hace que los logs sean fáciles de:

•Buscar
•Analizar
•Filtrar
•Analizar
•Reenviar a sistemas externos

El sistema utiliza múltiples niveles de logging:

Nivel	Propósito
DEBUG	Flujo de ejecución interno
INFO	Acciones de trading y actualizaciones de estado
WARNING	Comportamiento sospechoso o inesperado
ERROR	Fallos recuperables
CRITICAL	Problemas fatales del sistema

Archivos de Log Rotativos

El logger almacena automáticamente los logs en archivos rotativos utilizando RotatingFileHandler.

Las características incluyen:

•Persistencia automática de logs
•Límites de tamaño de archivo
•Copias de seguridad históricas
•Soporte de codificación UTF-8

Configuración:

Code

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

Esto evita el crecimiento descontrolado de logs mientras preserva los datos históricos de depuración.

El sistema mantiene:

•Log activo actual
•Hasta 5 archivos de log archivados
•250 MB por archivo

Este enfoque es especialmente importante para sistemas de trading de larga duración que operan continuamente 24/7.

Registro en Telegram en Tiempo Real

Una de las características clave de la infraestructura de ByNinja es que los logs del bot de trading se reenvían automáticamente al bot de Telegram en tiempo real.

La arquitectura funciona así:

Code

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

Cada evento importante generado por el bot de trading puede aparecer instantáneamente dentro del canal o chat privado de Telegram.

Ejemplos:

Code

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

Esto le da al operador visibilidad inmediata del sistema sin necesidad de acceso SSH o herramientas de monitoreo del servidor.

El mecanismo de reenvío se implementa a través de un manejador de logging TCP personalizado:

Code

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

El servidor de Telegram recibe mensajes a través de TCP y los reenvía directamente a la API del Bot de Telegram.

Esto transforma efectivamente a Telegram en un panel de monitoreo remoto en tiempo real para el motor de trading.

Flujo de Trabajo de Depuración

El flujo de trabajo de depuración está diseñado para un aislamiento y recuperación rápidos de problemas.

Paso 1 — Detectar el Problema

La mayoría de los problemas son inmediatamente visibles a través de las notificaciones de Telegram.

Ejemplo:

Code

❌ Error starting TCP client: Connection refused

Code

⚠️ Unknown message type

Debido a que los logs se entregan en tiempo real, los problemas a menudo se pueden detectar en cuestión de segundos.

Paso 2 — Inspeccionar Logs Detallados

Cuando se requiere una investigación más profunda, los desarrolladores pueden inspeccionar:

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

Los logs proporcionan rastros de ejecución cronológicos para:

•Decisiones de estrategia
•Ejecución de órdenes
•Comunicación TCP
•Interacciones de Telegram
•Operaciones de persistencia
•Eventos de apagado

Paso 3 — Reproducir el Escenario

El nivel DEBUG se puede habilitar para capturar:

•Transiciones de estado interno
•Flujo de mensajes TCP
•Ejecución de comandos
•Ciclo de vida de los hilos
•Operaciones de persistencia

Esto permite a los desarrolladores reproducir casos extremos difíciles y condiciones de carrera.

Paso 4 — Rastrear la Cadena de Fallos

Debido a que cada subsistema utiliza logging centralizado, se hace posible reconstruir la secuencia exacta de eventos que llevaron a un fallo.

Cadena de ejemplo:

Code

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

Esto es especialmente útil en sistemas asíncronos multi-hilo donde los problemas pueden originarse lejos del punto de fallo visible.

Rastreo de Errores

El sistema de logging está muy centrado en el rastreo estructurado de errores.

Todas las operaciones críticas están envueltas en bloques try/except con informes de error explícitos:

Code

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

Esto asegura que los fallos inesperados nunca desaparezcan silenciosamente.

El sistema rastrea errores a través de múltiples capas:

Capa	Ejemplos de Errores
API de Binance	Rechazo de orden, tiempo de espera
Capa TCP	Pérdida de conexión
Bot de Telegram	Fallos de API
Persistencia	Corrupción de archivo
Motor de Estrategia	Señales inválidas
Hilos	Bloqueos o fallos

Pro Tip: Usa un Editor de Código

Para una experiencia mucho mejor editando archivos de configuración, recomendamos usar un editor de código profesional como Visual Studio Code.

Download VS Code ↗

Registro de Apagado Graceful

El bot también registra las operaciones de apagado y recuperación.

Ejemplo:

Code

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

Esto es extremadamente importante en entornos de trading porque confirma que:

•Las posiciones se guardaron
•Los hilos se detuvieron correctamente
•Las operaciones pendientes se completaron
•La persistencia se vació con éxito

Operaciones Remotas a través de Telegram

La integración con Telegram no se limita a logs pasivos.

La misma infraestructura también soporta la ejecución de comandos remotos.

Ejemplos:

Code

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

Esto crea un flujo de trabajo operativo completamente remoto:

•Recibir alertas en Telegram
•Analizar logs
•Enviar comandos de recuperación
•Monitorear los resultados de la ejecución

Todo sin acceso directo al servidor.

Arquitectura de Monitoreo Orientada a Producción

La arquitectura de logging general combina varias prácticas de grado de producción:

•Logging centralizado
•Formateo estructurado
•Archivos de log rotativos
•Notificaciones remotas en tiempo real
•Logging seguro para multi-hilo
•Transmisión de logs por TCP
•Seguimiento de apagado graceful
•Control operativo remoto

Esto transforma el subsistema de logging de una simple utilidad de depuración a una infraestructura completa de monitoreo y operación para el trading automatizado de criptomonedas.