Buglapse

Обзор ​

Хлебная крошка — небольшая запись с временем о том, что произошло перед ошибкой: вызов консоли, исходящий запрос, шаг в вашем коде. SDK хранит скользящий след из них и прикрепляет его к следующему пойманному исключению, так что вы видите последовательность событий, приведших к сбою, а не только сам сбой.

Хлебные крошки путешествуют только с исключениями. Логи, трейсы и спаны следа не несут.

Добавление вручную ​

ts
import { addBreadcrumb, captureException } from '@buglapse/node'

addBreadcrumb({
    type: 'payment',
    level: 'info',
    message: 'Charging card',
    data: { orderId: order.id, amount: order.total },
})

try {
    await chargeCard(order)
} catch (error) {
    captureException(error) // уходит с крошкой выше в следе
}

Обязательно только message:

  • type — произвольная строка, по которой панель выбирает иконку и отрисовку. По умолчанию "debug".
  • level — log | info | warn | error | debug | success. По умолчанию "debug"; задаёт цвет маркера.
  • data — необязательные структурированные подробности, в панели показываются как JSON.
  • timestamp — проставляется автоматически.

Свой след у каждого запроса ​

На сервере один общий след смешал бы крошки всех параллельных запросов. Вместо этого у каждого асинхронного контекста свой:

  • Каждая область, начатая с верхнего уровня, — запрос, обработанный HttpServerIntegration, withScope() или asyncSpan() вокруг задачи — начинается с пустого следа. Её крошки никогда не появляются в ошибке другого запроса.
  • Вложенные в неё области и спаны разделяют её след, так что один запрос копит один след, как бы глубоко ваш код ни вкладывал withScope()/span().
  • Крошки, добавленные вне любой области (при старте, в таймере верхнего уровня), попадают в общий корневой след процесса. Они прикрепляются к ошибкам, пойманным вне области, но не к ошибкам внутри запроса.

Без HttpServerIntegration или своего withScope() на каждую единицу работы все запросы делят корневой след — тогда крошки в ошибке могут прийти из другого запроса.

Автоматические крошки ​

BreadcrumbsIntegration записывает крошку на каждый вызов console.* и каждый исходящий HTTP-запрос (fetch(), node:http, node:https и библиотеки поверх них) без изменений кода:

ts
import { use } from '@buglapse/node'
import { breadcrumbsIntegration } from '@buglapse/node/integrations'

use(breadcrumbsIntegration())

Ручные и автоматические крошки попадают в один след, в порядке, в котором происходили.

Ограничение следа ​

След хранит 50 последних крошек; когда он полон, при добавлении новой отбрасывается самая старая.

Хлебные крошки в панели ​

Страница исключения показывает его след над стектрейсом, начиная со старых. Маркер окрашен по level; type выбирает, как рисуется строка:

  • console — «Console {level}», с аргументами вызова (data.args) в подзаголовке.
  • http — метод и адрес, со статусом ответа рядом с заголовком (красным при уровне error). Прочие ключи в data показываются как JSON.
  • всё остальное — тип с заглавной буквы в заголовке и message в подзаголовке, data — как JSON.