Быстрый старт

Если SDK уже подключён, перед обновлением ознакомьтесь с руководством по миграции.

Регистрация и настройка
Установка
Модули Tracer JS SDK
Базовая инициализация
Дополнительные возможности инициализации SDK
Доступ к SDK модулям (getTracerModules())
Отключение модулей (disableTracerModules())

Регистрация и настройка

Зайти в аккаунт Tracer.
Создать или вступить в организацию (нужно запросить ссылку-приглашение у администратора или владельца).
Добавить JS проект (нужно быть администратором или владельцем организации).
Для интеграции понадобится appToken из настроек проекта

Установка

Для установки необходимых пакетов введите в терминале команду:

npm install @apptracer/sdk --save

В примерах BUILD_VERSION_NAME — строка с версией вашего приложения. Подставьте значение из своей сборки.

Модули Tracer JS SDK

SDK разделён на функциональные модули (initTracer-названиемодуля), отвечающие за сбор и хранение информации о событиях, и модули отправки данных (initTracer-названиемодуля-Uploader), необходимые для загрузки собранных данных в Трейсер:

Модуль	Описание
`initTracerError`	Отвечает за сбор глобальных событий и ручную регистрацию ошибок в проекте. Подробнее в Crash и Non-Fatal
`initTracerErrorAsyncStack`	Дополняет стеки ошибок цепочкой асинхронных вызовов. Для регистрации ошибок нужен `initTracerError`. Подробнее в Crash и Non-Fatal
`initTracerLog`	Отвечает за хранение логов событий, предшествующих сбою. Подробнее в Добавление информации к событиям
`initTracerPlugins`	Отвечает за инициализацию плагинов SDK. Подробнее в Плагины
`initTracerErrorUploader`	Отвечает за отправку данных о событиях в сервис.
`initTracerSession`	Необязательная настройка сессии. Для сбора и отправки активности достаточно `initTracerSessionUploader`. Параметры.
`initTracerSessionUploader`	Отвечает за отправку данных о состоянии сессий приложения в сервис.

Подключайте только те модули, которые нужны вашему приложению. Их можно загружать отдельно и инициализировать на разных этапах запуска, чтобы уменьшить размер начального бандла.

Например, модуль ошибок стоит подключить как можно раньше, чтобы собирать сбои во время загрузки приложения. Модуль отправки можно загрузить позже, отдельным бандлом, когда основная часть страницы уже готова.

В браузере и Node.js используйте один и тот же импорт — @apptracer/sdk. Подходящая сборка выбирается по условиям browser и node в exports пакета. Если вы используете сборщик, укажите в его настройках целевую платформу.

Совместимость и точки входа

Импорт	Назначение
`@apptracer/sdk`	Main: браузерная сборка с синтаксисом ES2015 или Node.js-сборка с синтаксисом ES2020.
`@apptracer/sdk/lite`	Именованные экземпляры для браузерных библиотек. Подробнее о Lite.
`@apptracer/sdk/legacy`	Main для старых браузеров: тот же API, синтаксис ES5.
`@apptracer/sdk/legacy/lite`	Lite для старых браузеров: тот же API, синтаксис ES5.

Все сборки поставляются как ES-модули. Если браузер не поддерживает ESM, преобразуйте их при сборке приложения.

SDK не включает полифилы. Добавьте в приложение те, которые нужны вашим браузерам и подключённым модулям. Например, для OpenTelemetry необходим Promise, а для Web Vitals — Map, Promise и PerformanceObserver. Использование Legacy-сборки само по себе не добавляет поддержку этих API.

initTracerErrorAsyncStack и initTracerPerformanceWebVitals доступны в основной браузерной версии SDK. Модуль памяти initTracerPerformanceMemory также доступен в Lite. В Node.js этих модулей нет.

Модули сессий, initTracerSdk, функции отключения и возобновления работы, а также функции идентификатора устройства доступны в основной версии SDK. OpenTelemetry можно использовать и в основной версии, и в Lite.

Примеры ниже показывают отдельные варианты подключения. Если модуль уже подключён в вашем приложении, используйте его экземпляр через getTracerModules() и не повторяйте соответствующий initTracer* из другого примера.

Node.js

В Node.js SDK подписывается на события uncaughtException и unhandledRejection. Его обработчики не завершают процесс: это должно делать приложение в соответствии со своей логикой обработки ошибок. Если вы уже обрабатываете эти события самостоятельно, передайте disableUnhandledErrorsListeners: true и регистрируйте ошибки вручную.

Инициализаторы initTracer*Uploader в Node.js дополнительно принимают tlsAgent — экземпляр https.Agent, например для собственного центра сертификации:

import { Agent } from 'node:https';
import { readFileSync } from 'node:fs';
import { initTracerError, initTracerErrorUploader } from '@apptracer/sdk';

initTracerError();
initTracerErrorUploader({
    appToken: 'appToken из настроек в Трейсере',
    versionName: BUILD_VERSION_NAME, // строка с версией приложения из вашей сборки
    // Путь к PEM-файлу сертификата вашего центра сертификации.
    tlsAgent: new Agent({ ca: readFileSync('/path/to/ca.pem') }),
});

В Node.js модуль initTracerErrorUploader при запуске повторяет запросы, сохранённые при предыдущем завершении процесса. Для всей сохранённой очереди, включая запросы других модулей, используется его текущий tlsAgent.

SDK также обрабатывает SIGTERM, SIGINT и beforeExit, чтобы сохранить неотправленные запросы. Его обработчики сигналов сами не завершают процесс — завершение по SIGTERM и SIGINT должно обеспечить приложение.

Базовая инициализация

Для сбора и отправки ошибок подключите initTracerError и initTracerErrorUploader:

В вашем app.js:

import { initTracerError, initTracerErrorUploader } from '@apptracer/sdk';

// Подписываемся на глобальные события ошибок
initTracerError();

// Инициализируем Трейсер для отправки зарегистрированных ошибок
initTracerErrorUploader({
    versionName: BUILD_VERSION_NAME, // строка с версией приложения из вашей сборки
    appToken: 'appToken из настроек в Трейсере',
});

Общие параметры модулей отправки -Uploader:

Параметр	Тип	Обязательный	Описание
`appToken`	`string`	Да	Персональный токен вашего проекта в Tracer. Можно найти в разделе Настройки (нужно быть администратором или владельцем организации).
`versionName`	`string`	Да	Отображаемое имя версии. Чаще всего используется версия из `package.json`.
`versionCode`	`number`	Нет	Порядковый номер версии вашего приложения. В интерфейсе `versionCode` группируется по `versionName`. `versionCode` можно не указывать — он сформируется автоматически на основе `versionName`, если `versionName` соответствует формату `prefix-major.minor.patch-postfix`, где дефисы, `prefix` и `postfix` необязательны.
`apiHost`	`string`	Нет	API-хост без схемы и пути. SDK добавляет `https://`. В браузере можно указать порт; в Node.js используется стандартный HTTPS-порт. См. проксирование.
`environment`	`string`	Нет	Окружение приложения, например `prod/test/dev`. Передаётся модулями ошибок и сессий и используется при фильтрации crash-free. Модуль Performance этот параметр не использует; для метрик задайте атрибут окружения.

Если в процессе инициализации у вас возникли сложности, вы можете задать вопрос в нашем чате поддержки

Дополнительные возможности инициализации SDK

Единая конфигурация для Uploader-ов

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

import { initTracerError, initTracerErrorUploader, initTracerSessionUploader } from '@apptracer/sdk';

initTracerError();

const config = {
    versionName: BUILD_VERSION_NAME, // строка с версией приложения из вашей сборки
    appToken: 'appToken из настроек в Трейсере',
};

initTracerErrorUploader(config);
initTracerSessionUploader(config);

Единый объект SDK (initTracerSdk(config: T, ...moduleInit: U))

У каждого модуля сбора есть свои настройки. Их можно передать вместе с настройками отправки в initTracerSdk, чтобы получить один объект с методами всех подключённых модулей:

import { initTracerError, initTracerErrorUploader, initTracerLog, initTracerSdk } from '@apptracer/sdk';

const tracerSdk = initTracerSdk(
    {
        versionName: BUILD_VERSION_NAME, // строка с версией приложения из вашей сборки
        appToken: 'appToken из настроек в Трейсере',
    },
    initTracerLog,
    initTracerError,
    initTracerErrorUploader,
);

export { tracerSdk };

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

Доступ к SDK модулям (getTracerModules())

Каждый модуль нужно инициализировать один раз. Повторный вызов initTracer* вызывает исключение, даже если параметры не изменились. Это относится и к модулям отправки, и к Web Vitals. Чтобы получить уже подключённый модуль, используйте getTracerModules():

import { getTracerModules } from '@apptracer/sdk';

// ITracerLog | undefined
const tracerLog = getTracerModules().log;

tracerLog?.log('some info');

getTracerModules() возвращает объект с подключёнными модулями, доступный только для чтения (readonly). До инициализации соответствующее поле отсутствует.

Обращайтесь к нужному полю: error, log, performance, memory, async, plugins или session. Набор полей зависит от платформы. Модули отправки и Web Vitals не возвращают экземпляр для работы с ним, поэтому перебирать все поля объекта не рекомендуется.

Отключение модулей (disableTracerModules())

disableTracerModules() приостанавливает основную версию SDK. Для продолжения работы вызовите enableTracerModules(). Модули сохраняются, повторно инициализировать их не нужно.

import { disableTracerModules, enableTracerModules } from '@apptracer/sdk';

disableTracerModules(); // очистить неотправленные данные и поставить сбор на паузу
enableTracerModules(); // возобновить работу с прежними настройками

По умолчанию при отключении очищаются неотправленные данные, в том числе пакеты, которые ещё готовятся к отправке. Чтобы сохранить очередь ошибок, метрики и накопленные логи до возобновления работы, передайте disableTracerModules({ keepData: true }). В Node.js при этом сохраняется и файл запросов для следующего запуска.

Настройки, общий контекст, ключи, пользователь, плагины и сессия сохраняются в обоих случаях. Новые события во время паузы не собираются.

Уже отправленные HTTP-запросы завершаются как обычно: SDK обрабатывает ответ и вызывает обработчик результата. Повторные отправки отменяются и не возобновляются после enableTracerModules().

Незавершённые таймеры и замеры отменяются даже при keepData: true. Подробнее о фоновых замерах — в описании модуля памяти.

Обработчики асинхронных операций приложения продолжают работать, но SDK не собирает для них контекст. Пауза основной версии не влияет на экземпляры Lite и отдельно подключённый TracerUploadSpanExporter.

При временных ошибках отправки число повторов по умолчанию не ограничено. Публичной настройки количества и интервалов повторов нет.