Breadcrumbs

Breadcrumbs — хронологический след действий и событий до ошибки. Они прикрепляются к ивенту в Хоуке и помогают понять что происходило перед падением. В Node.js нет автоматического сбора как в браузере (сеть, SPA-навигация, клики) — цепочку строите через HawkCatcher.breadcrumbs.add().

Зачем это нужно

Контекст сценария: стек показывает место ошибки, breadcrumbs — путь выполнения к этой точке

Прозрачность серверного потока: шаги фиксируются там, где вы явно вызываете add()

Бизнес-логика: этапы сценария, идентификаторы сущностей (без секретов и лишнего PII)

Подключение

Инициализация — HawkCatcher.init() (singleton). До init() буфер breadcrumbs по сути не используется.

import HawkCatcher from '@hawk.so/nodejs'; HawkCatcher.init({ token: 'INTEGRATION_TOKEN', breadcrumbs: { maxBreadcrumbs: 15, beforeBreadcrumb(breadcrumb, hint) { return breadcrumb; }, }, });

Отключить полностью:

HawkCatcher.init({ token: 'INTEGRATION_TOKEN', breadcrumbs: false, });

Параметры breadcrumbs при init

В Node доступны только два поля. Полей trackFetch, trackNavigation, trackClicks (как в браузерном SDK) нет.

Параметр	Назначение
`maxBreadcrumbs`	Лимит буфера (по умолчанию 15). При переполнении удаляются самые старые записи (FIFO)
`beforeBreadcrumb`	Хук перед сохранением записи в буфер

beforeBreadcrumb

Вызывается перед попаданием записи в буфер. Второй аргумент hint — ваш контекст: при add(breadcrumb, hint) вы сами передаёте то, что нужно в хуке; SDK в Node сам не заполняет hint из DOM/Response.

вернуть breadcrumb (можно изменённый) — запись сохранится в таком виде;

вернуть false — запись не сохраняется;

любой иной результат — сохраняется исходная запись, в консоль пишется предупреждение.

API

Методы на HawkCatcher.breadcrumbs (статические). Если breadcrumbs: false или init() не вызывали, add / clear по сути no-op, get() вернёт пустой массив.

HawkCatcher.breadcrumbs.add(breadcrumb, hint?) — добавить запись (учитываются beforeBreadcrumb и лимит).

HawkCatcher.breadcrumbs.get() — копия записей от старых к новым.

HawkCatcher.breadcrumbs.clear() — очистить буфер в памяти процесса.

По умолчанию до 15 записей (FIFO). После отправки события буфер сам не очищается — при необходимости вызывайте clear().

Ручная запись

HawkCatcher.breadcrumbs.add({ type: 'logic', category: 'checkout', message: 'Payment intent created', level: 'info', data: { step: 2 }, });

Где смотреть в Hawk

Цепочка breadcrumbs отображается в карточке ивента вместе с ошибкой.