Логування та налагодження

Надійне логування є одним із ключових компонентів архітектури ByNinja Trading Bot. Кожна важлива дія всередині системи реєструється, структурується та пересилається в реальному часі через інтеграцію з Telegram. Це дозволяє трейдерам віддалено моніторити бота, миттєво виявляти проблеми та налагоджувати складні торгові сценарії без прямого доступу до сервера.

Система логування розроблена для досягнення трьох основних цілей:

  • •Моніторинг у реальному часі
  • •Детальна діагностика помилок
  • •Віддалене спостереження через Telegram

На відміну від базових реалізацій лише для консолі, інфраструктура ByNinja об'єднує ротаційні файлові логи, виведення в консоль, пересилання по TCP та доставку в Telegram у єдиний конвеєр моніторингу.

Структура логів

Бот використовує централізовану архітектуру логування, побудовану на основі модуля Python logging.

Кожне повідомлення логу дотримується стандартизованої структури:

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

Форматер включає:

  • •Часову мітку
  • •Ім'я логера
  • •Рівень серйозності
  • •Зрозуміле для людини повідомлення

Приклад конфігурації форматера:

Code
'%(asctime)s - %(name)s - %(levelname)s - %(message)s'

Ця структура робить логи зручними для:

  • •Пошуку
  • •Парсингу
  • •Фільтрації
  • •Аналізу
  • •Пересилання до зовнішніх систем

Система використовує кілька рівнів логування:

РівеньПризначення
DEBUGВнутрішній потік виконання
INFOТоргові дії та оновлення статусу
WARNINGПідозріла або неочікувана поведінка
ERRORПомилки, що підлягають відновленню
CRITICALКритичні системні проблеми

Ротаційні файлові логи

Логер автоматично зберігає логи в файли, що ротуються, використовуючи RotatingFileHandler.

Функції включають:

  • •Автоматичне збереження логів
  • •Обмеження розміру файлу
  • •Історичні резервні копії
  • •Підтримку кодування UTF-8

Конфігурація:

Code
RotatingFileHandler(
    filename=self._log_file,
    maxBytes=250*1024*1024,
    backupCount=5,
    encoding='utf-8'
)

Це запобігає неконтрольованому зростанню логів, зберігаючи при цьому історичні дані для налагодження.

Система зберігає:

  • •Поточний активний лог
  • •До 5 заархівованих файлів логів
  • •250 МБ на файл

Цей підхід є особливо важливим для довгострокових торгових систем, що працюють безперервно 24/7.

Логування в Telegram у реальному часі

Однією з ключових особливостей інфраструктури ByNinja є те, що логи торгового бота автоматично пересилаються в Telegram бот у реальному часі.

Архітектура працює так:

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

Кожна важлива подія, згенерована торговим ботом, може миттєво з'являтися у приватному Telegram каналі або чаті.

Приклади:

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

Це дає оператору миттєву видимість системи без доступу по SSH або інструментів моніторингу сервера.

Механізм пересилання реалізовано через спеціальний TCP-обробник логів:

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

Сервер Telegram отримує повідомлення через TCP і пересилає їх безпосередньо в Telegram Bot API.

Це фактично перетворює Telegram на панель віддаленого моніторингу торгового ядра в реальному часі.

Процес налагодження

Робочий процес налагодження призначений для швидкого ізолювання проблем та відновлення.

Крок 1 — Виявлення проблеми

Більшість проблем одразу видно через сповіщення в Telegram.

Приклад:

Code
❌ Error starting TCP client: Connection refused

або:

Code
⚠️ Unknown message type

Оскільки логи доставляються в реальному часі, проблеми часто можна виявити за лічені секунди.

Крок 2 — Перевірка детальних логів

Коли потрібне глибше розслідування, розробники можуть перевірити:

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

Логи надають хронологічні сліди виконання для:

  • •Стратегічних рішень
  • •Виконання ордерів
  • •TCP комунікації
  • •Взаємодії з Telegram
  • •Операцій збереження
  • •Подій завершення роботи

Крок 3 — Відтворення сценарію

Рівень DEBUG може бути увімкнений для запису:

  • •Внутрішніх переходів станів
  • •Потоку повідомлень TCP
  • •Виконання команд
  • •Життєвого циклу потоків
  • •Операцій збереження

Це дозволяє розробникам відтворювати складні крайові випадки та стани гонитви.

Крок 4 — Відстеження ланцюжка збоїв

Оскільки кожна підсистема використовує централізоване логування, стає можливим відновити точну послідовність подій, що призвели до збою.

Приклад ланцюжка:

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

Це особливо корисно в асинхронних багатопотокових системах, де проблеми можуть виникати далеко від видимої точки збою.

Відстеження помилок

Система логування сильно орієнтована на структуроване відстеження помилок.

Усі критичні операції обгорнуті в блоки try/except з явним повідомленням про помилку:

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

Це гарантує, що неочікувані збої ніколи мовчки не зникнуть.

Система відстежує помилки на кількох рівнях:

РівеньПриклади помилок
API BinanceВідхилення ордера, тайм-аут
TCP-рівеньВтрата з'єднання
Telegram ботЗбої API
ЗбереженняПошкодження файлу
Стратегічне ядроНедійсні сигнали
ПотокиВзаємне блокування або збої

Порада: Використовуйте редактор коду

Для зручнішого редагування конфігураційних файлів ми рекомендуємо використовувати професійний редактор коду, наприклад Visual Studio Code.

Download VS Code ↗

Логування безпечного завершення роботи

Бот також логує операції завершення роботи та відновлення.

Приклад:

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

Це надзвичайно важливо в торговельних середовищах, оскільки це підтверджує, що:

  • •Позиції були збережені
  • •Потоки зупинилися коректно
  • •Очікувані операції завершилися
  • •Дані успішно скинуті на диск

Віддалені операції через Telegram

Інтеграція з Telegram не обмежується пасивними логами.

Та ж сама інфраструктура також підтримує віддалене виконання команд.

Приклади:

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

Це створює повністю віддалений операційний робочий процес:

  • •Отримуйте сповіщення в Telegram
  • •Аналізуйте логи
  • •Надсилайте команди на відновлення
  • •Контролюйте результати виконання

Усе це без прямого доступу до сервера.

Архітектура моніторингу, орієнтована на продакшн

Загальна архітектура логування поєднує в собі кілька практик рівня продакшн:

  • •Централізоване логування
  • •Структуроване форматування
  • •Ротаційні файли логів
  • •Віддалені сповіщення в реальному часі
  • •Багатопотоково-безпечне логування
  • •TCP-стрімінг логів
  • •Відстеження безпечного завершення роботи
  • •Віддалений оперативний контроль

Це перетворює підсистему логування з простої утиліти для налагодження на повноцінну інфраструктуру моніторингу та управління для автоматизованої криптоторгівлі.