Включение debug режима

STOMP.js предоставляет встроенные механизмы отладки, позволяющие отслеживать внутренние события протокола STOMP, контролировать обмен кадрами (frames), диагностировать проблемы соединения и анализировать поведение брокера сообщений. Debug-режим в библиотеке не является отдельным модулем, а реализуется через конфигурационные параметры клиента, прежде всего через функцию логирования debug.

В основе отладочного режима лежит передача пользовательской функции в параметр debug при создании клиента. Эта функция вызывается библиотекой каждый раз, когда необходимо вывести диагностическую информацию.

Фактически STOMP.js не навязывает формат логирования. Вместо этого разработчик получает полный контроль над тем, как обрабатывать сообщения отладки: вывод в консоль, отправка в удалённый лог-сервис, буферизация или полное подавление.

Ключевой принцип заключается в том, что debug-режим активируется только при наличии обработчика. Если функция не задана, библиотека работает в «тихом» режиме без диагностического вывода.

Конфигурация клиента с debug-параметром

Инициализация клиента STOMP.js с включённой отладкой выполняется через объект конфигурации:

import { Client } from '@stomp/stompjs';

const client = new Client({
  brokerURL: 'ws://localhost:15674/ws',
  debug: function (str) {
    console.log('[STOMP]', str);
  }
});

В данном примере каждая внутренняя операция STOMP.js будет сопровождаться вызовом функции debug, а строка с диагностикой будет выводиться в консоль.

Функция debug получает строку, содержащую информацию о внутренних событиях: подключение, отправка кадров, подтверждения, ошибки парсинга, состояния heartbeat и переподключения.

Формат debug-сообщений

Сообщения, поступающие в debug-обработчик, не имеют строго фиксированного формата, однако содержат структурированную информацию, удобную для анализа. Обычно они включают:

тип события (CONNECT, CONNECTED, MESSAGE, ERROR, DISCONNECT)
направление потока (outgoing / incoming)
содержимое STOMP frame
внутренние состояния клиента

Пример типичных сообщений:

>>> CONNECT
accept-version:1.2
heart-beat:10000,10000

<<< CONNECTED
version:1.2
heart-beat:0,0

Такая структура позволяет отслеживать полный жизненный цикл соединения.

Включение расширенного логирования

Debug-функция может использоваться не только для вывода строк, но и для расширенного анализа. Часто применяется обёртка, добавляющая временные метки и уровни логирования:

const client = new Client({
  brokerURL: 'ws://localhost:15674/ws',
  debug: (msg) => {
    const timestamp = new Date().toISOString();
    console.log(`${timestamp} STOMP DEBUG: ${msg}`);
  }
});

Это позволяет синхронизировать события STOMP с другими логами системы и упрощает диагностику асинхронных ошибок.

Отключение debug-режима

Отключение отладки достигается простым удалением обработчика или передачей пустой функции:

const client = new Client({
  brokerURL: 'ws://localhost:15674/ws',
  debug: () => {}
});

При таком подходе библиотека продолжает формировать диагностические строки, но они не обрабатываются и фактически игнорируются.

Некоторые реализации предпочитают условное включение debug-режима через переменные окружения:

const isDebug = true;

const client = new Client({
  brokerURL: 'ws://localhost:15674/ws',
  debug: isDebug ? (msg) => console.log(msg) : () => {}
});

Debug и жизненный цикл соединения

Отладочный режим наиболее полезен при анализе жизненного цикла STOMP-соединения. В логах можно наблюдать последовательность событий:

Инициализация клиента
Попытка подключения к WebSocket
Отправка CONNECT frame
Получение CONNECTED frame
Подписка на destination
Приём MESSAGE frames
Закрытие соединения

Каждый этап фиксируется через debug-вывод, что позволяет точно определить момент возникновения ошибки.

Отладка heartbeat

STOMP.js поддерживает механизм heartbeat, который также отображается в debug-логах. При включённой диагностике можно наблюдать обмен контрольными сигналами:

heart-beat send: 10000
heart-beat receive: 10000

Если heartbeat нарушается, в debug-выводе появляются сообщения о таймаутах и разрывах соединения. Это особенно важно при работе через нестабильные WebSocket-соединения или прокси-серверы.

Анализ входящих и исходящих кадров

Debug-режим позволяет различать направление STOMP-кадров:

>>> — исходящие кадры (от клиента к брокеру)
<<< — входящие кадры (от брокера к клиенту)

Пример отправки сообщения:

>>> SEND
destination:/queue/orders
content-length:13

Hello STOMP

Пример получения сообщения:

<<< MESSAGE
destination:/queue/orders
message-id:001
Hello STOMP

Такое разделение критично при отладке очередей и маршрутизации сообщений.

Перехват ошибок через debug

Ошибки протокола STOMP также поступают в debug-обработчик. Это могут быть:

некорректные кадры
ошибки аутентификации
сбои соединения
отказ брокера

Пример:

<<< ERROR
message:Malformed frame received
content-type:text/plain

При этом debug-режим не заменяет обработчик onStompError, но позволяет получить дополнительный контекст.

Интеграция debug с внешними системами логирования

Функция debug может использоваться как точка интеграции с системами мониторинга. Вместо console.log данные могут отправляться в централизованные системы:

const client = new Client({
  brokerURL: 'ws://localhost:15674/ws',
  debug: (msg) => {
    fetch('/logs', {
      method: 'POST',
      body: JSON.stringify({ message: msg })
    });
  }
});

Такая схема позволяет собирать телеметрию работы STOMP-клиентов в распределённых системах.

Производительность debug-режима

Следует учитывать, что активный debug-режим увеличивает нагрузку на приложение. Причины:

частые вызовы функции debug
сериализация строк логов
синхронные операции (console.log)
возможные сетевые запросы при интеграции с внешними системами

В высоконагруженных системах debug рекомендуется отключать или ограничивать выборочной фильтрацией сообщений.

Фильтрация debug-сообщений

Для уменьшения объёма логов может использоваться фильтрация:

const client = new Client({
  brokerURL: 'ws://localhost:15674/ws',
  debug: (msg) => {
    if (msg.includes('ERROR') || msg.includes('CONNECTED')) {
      console.log(msg);
    }
  }
});

Такой подход позволяет сосредоточиться на критических событиях, исключая шум от heartbeat и технических кадров.

Поведение debug в различных средах

Поведение debug-режима может отличаться в зависимости от среды выполнения:

браузер: вывод в DevTools console
Node.js: вывод в stdout/stderr
серверные среды: интеграция с логгерами (Winston, Bunyan)

STOMP.js не накладывает ограничений на среду, поэтому debug-обработчик полностью определяется архитектурой приложения.

Debug и асинхронная природа WebSocket

Поскольку STOMP.js работает поверх WebSocket, события приходят асинхронно. Debug-логирование фиксирует эти события в реальном времени, что делает возможным анализ гонок, задержек и нарушений порядка сообщений.

При корректной интерпретации логов можно выявить:

задержки доставки MESSAGE frames
повторные подключения
разрывы соединения без явного DISCONNECT
несоответствие heartbeat интервалов

Такая информация критична при разработке систем реального времени, использующих STOMP поверх брокеров сообщений вроде ActiveMQ, RabbitMQ или Artemis.