Buglapse

Node SDK Buglapse ловит ошибки, логи, трейсы и метрики спанов процесса Node.js — API-сервера, воркера очереди, cron-скрипта. Проект определяется DSN (https://{key}@{host}) — он лежит в Настройки → Общие проекта.

Установка ​

Пока SDK не опубликован в публичном npm, пакеты @buglapse/* раздаёт сам Buglapse. Один раз укажите scope в .npmrc рядом с package.json:

ini
@buglapse:registry=https://app.buglapse.com/npm/

Дальше ставьте как обычно — npm update подхватывает новые версии, как у любой зависимости:

bash
npm install @buglapse/node

Нужен Node 18.19 или новее. В пакете есть сборки и ESM, и CommonJS, так что работают и import, и require().

Инициализация ​

Вызовите init() как можно раньше — в начале точки входа, до импорта остального приложения и до того, как сервер начнёт слушать:

ts
import { init } from '@buglapse/node'

init({
    dsn: process.env.BUGLAPSE_DSN,
    environment: process.env.NODE_ENV,
    release: process.env.GIT_SHA,
})

Всё экспортируется именованными функциями из @buglapse/node (captureException, log, asyncSpan, ...); встроенные интеграции лежат в отдельном входе, @buglapse/node/integrations.

Сам по себе init() ловит только падения (см. ниже). Для типичного API-сервера включите изоляцию и трейсинг запросов, контекст рантайма и хлебные крошки:

ts
import { init } from '@buglapse/node'
import {
    breadcrumbsIntegration,
    httpErrorsIntegration,
    httpServerIntegration,
    httpTracingIntegration,
    nodeContextIntegration,
} from '@buglapse/node/integrations'

init({
    dsn: process.env.BUGLAPSE_DSN,
    environment: process.env.NODE_ENV,
    integrations: [
        httpServerIntegration(),   // своя область, крошки и трейс на каждый входящий запрос
        httpTracingIntegration(),  // исходящие запросы — дочерними спанами
        httpErrorsIntegration(),   // неудачные исходящие запросы — логами ошибок
        breadcrumbsIntegration(),  // вызовы консоли и исходящие запросы — хлебными крошками
        nodeContextIntegration(),  // версия Node, ОС и имя хоста в каждом событии
    ],
})

Каждая описана на своей странице в разделе Интеграции.

Что работает сразу ​

Сразу после init() UncaughtExceptionIntegration слушает события процесса uncaughtException и unhandledRejection: о падении сообщается, буфер событий выталкивается, и процесс завершается с кодом 1, как сделал бы сам Node. ContextLinesIntegration отправляет строки кода вокруг каждого кадра стека, так что страница инцидента показывает код, где произошла ошибка. Больше ничего по умолчанию не включено.

Ошибки, которые фреймворк ловит сам, — throw внутри обработчика маршрута Express или Fastify, — никогда не становятся необработанными, поэтому нужна одна строка в обработчике ошибок фреймворка. См. Ошибки.

Первое событие вручную ​

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

addBreadcrumb({ type: 'job', level: 'info', message: 'Started invoice export' })

try {
    await exportInvoices()
} catch (error) {
    captureException(error)
}

log.info('Invoice export finished', { count: 42 })

Откройте раздел Исключения проекта — через несколько секунд оно появится; лог окажется в Логах.

Перед деплоем ​

  • Разрешённые домены. Node не отправляет заголовок Origin. Если у проекта есть список в Настройки → Безопасность и приватность → Разрешённые домены, каждый запрос с сервера отклоняется с 403. Держите этот список пустым для серверных проектов — или заведите отдельный проект Buglapse для сервера и для браузера.
  • Короткоживущие процессы. События собираются в пачки и отправляются в фоне. Скрипт, CLI-команда или serverless-функция, которые заканчиваются process.exit() или замораживаются платформой, должны сначала выполнить await flush() — см. Транспорты.
  • DSN. Его безопасно хранить в переменной окружения или хранилище секретов; он разрешает только отправлять события, но не читать их.