В версии 3.0 изменились инициализация модулей, их отключение и подключение Web Vitals. Ниже описано, что нужно изменить в приложении при переходе с 2.x.
npm install @apptracer/sdk --save
Если SDK подключён в нескольких бандлах приложения, обновите его во всех. Версии 2.x и 3.0 хранят данные отдельно и не передают друг другу настройки. При одновременной загрузке обе версии могут собрать и отправить одну и ту же ошибку.
Обычные импорты — @apptracer/sdk и @apptracer/sdk/lite. Для старых браузеров предусмотрены @apptracer/sdk/legacy и @apptracer/sdk/legacy/lite. Legacy — это API 3.0 с ES5-синтаксисом, а не совместимость с API 2.x. Полифилы и преобразование внешних библиотек обеспечивает приложение. П одробнее о платформах и точках входа.
В 3.0 повторная инициализация отклоняется для всех публичных модулей, включая модули отправки и Web Vitals. Повторный вызов initTracer* вызывает исключение, даже если параметры не изменились. Чтобы получить уже подключённый модуль, используйте getTracerModules():
import { getTracerModules } from '@apptracer/sdk'; getTracerModules().error?.error(new Error('Operation failed'));
В Lite передайте имя экземпляра: getTracerModules('myModule') из @apptracer/sdk/lite. Разместите инициализацию при запуске приложения, чтобы она не повторялась при HMR, повторном монтировании компонента или загрузке другого бандла.
initTracerSdk подключает модули в указанном порядке. Если один из них не удалось подключить, предыдущие продолжают работать, а следующие не запускаются.
disableTracerModules() теперь приостанавливает основную версию SDK. По умолчанию неотправленные данные очищаются, а сами модули, настройки, контекст, пользователь, плагины и сессия сохраняются. Для продолжения работы вызовите enableTracerModules(). Повторно вызывать initTracer* не нужно.
В 3.0 появился параметр keepData: передайте disableTracerModules({ keepData: true }), чтобы сохранить неотправленные ошибки, метрики и накопленные логи на время паузы. В 2.x этого параметра не было. Незавершённые таймеры и замеры при этом отменяются. Уже отправленные HTTP-запросы завершаются, а отменённые повторные отправки после паузы не возобновляются.
Пауза основной версии SDK не влияет на Lite и отдельно подключённый экспортёр OpenTelemetry. Подробнее см. в описании отключения модулей.
| В 2.x | В 3.0 |
|---|---|
initTracerWebVitals | initTracerPerformanceWebVitals({ webVitals, ... }). Приложение устанавливает web-vitals и передаёт onCLS, onFCP, onLCP, onINP, onTTFB. |
initTracerWebVitalsUploader | Общий initTracerPerformanceUploader; инициализируйте его один раз вместе с остальными метриками. |
addMetricAttributes | webVitalsMetricAttributes. |
Библиотеку web-vitals теперь нужно установить отдельно и передать её функции в объекте webVitals. Это нужно сделать и в том случае, если вы уже использовали initTracerPerformanceWebVitals в 2.x: вызова без аргумента или только с webVitalsMetricAttributes больше недостаточно.
В TypeScript замените удалённый интерфейс ITracerWebVitalsConfig на ITracerPerformanceWebVitalsConfig<typeof webVitals>. Пример подключения приведён на странице Web Vitals.
| Старый API | Что делать |
|---|---|
userAgentData в конфигурации модуля отправки | Удалить параметр: сведения о среде определяются автоматически SDK и сервером. Произвольные сведения приложения передавайте через ключи или JSON-контекст ошибки. |
errorInfo.documentVisibilityState | В фильтрах и плагинах читать errorInfo.properties.documentVisibilityState. Поле относится к браузеру; в Node.js на него не полагайтесь. |
restrictOtherErrorListeners | Удалить из конфигурации. Основная версия SDK не блокирует обработчики ошибок приложения или Lite. Для ручного сбора без глобальных обработчиков задайте в ней disableUnhandledErrorsListeners: true. В Lite глобальные обработчики выключены по умолчанию; enableUnhandledErrorsListeners: true включает их. |
disableCheckNativeFunctions | Удалить из конфигурации асинхронных стеков. Использовать настройки подключения обработчиков, maxChainDepth и collapseRepeats. |
setModule() / removeModule() | Для окружения использовать environment в конфигурации модулей отправки ошибок и сессий; для поиска — ключи ошибки. Для компонента приложения — setTracerComponentName() или component конкретного события. |
Методы setModule(), removeModule() и настройка disableCheckNativeFunctions отсутствовали уже в 2.6.9. Если они остались в вашей интеграции, обновите её по таблице выше.
Во всех инициализаторах Lite имя экземпляра передаётся отдельным первым аргументом, например initTracerPlugins('myModule', { plugins: [...] }).
Импорты @apptracer/sdk/custom/* удалены. Замените их импортами из публичных точек входа: @apptracer/sdk, @apptracer/sdk/lite или соответствующих legacy-сборок. Неиспользуемые модули сборщик приложения может исключить с помощью tree shaking.
Сборка SDK тепер ь состоит из нескольких ES-модулей. Если вы копируете её файлы вручную, сохраняйте структуру каталогов вместе с зависимостями из modules: одного index.mjs недостаточно.
Объект, который возвращает getTracerModules(), теперь доступен только для чтения (readonly). Работайте с модулями через их методы, не заменяя поля этого объекта.
disableAsyncStack() и ITracerPerformanceTimerEnd пока сохранены для совместимости, но помечены как устаревшие. Вместо них используйте destroy() и ITracerPerformanceTimer. Если нужно временно приостановить сбор асинхронных стеков вместе с остальными модулями, вызовите disableTracerModules(), а для продолжения — enableTracerModules().
Экспортёр перенесён из отдельного пакета @apptracer/opentelemetry в SDK. Замените импорт:
import { TracerUploadSpanExporter } from '@apptracer/sdk';
Удалите зависимость @apptracer/opentelemetry, если других её использований не осталось. Сам OpenTelemetry по-прежнему устанавливает приложение; примеры подключения используют OpenTelemetry SDK 2.x.
Добавьте new TracerSpanProcessor() в spanProcessors провайдера перед процессором отправки, как в примерах подключения. В 2.x экспортёр добавлял UUID сессии в Resource и корневые спаны, а ID пользователя — в корневые спаны при отправке. В 3.0 эти данные добавляет процессор в каждый спан при его создании. Сам экспортёр больше не дополняет ими спаны и Resource.
Обработчик результата export() теперь вызывается после завершения отправки. Методы forceFlush() и shutdown() дожидаются текущих запросов и сообщают об ошибке, если отправка не удалась. Пока SDK повторяет запросы к недоступному серверу, эти методы продолжают ждать.
Для переноса контекста OpenTelemetry через браузерные асинхронные обработчики подключите TracerContextManager.
Если вы используете @apptracer/sourcemap в сборке приложения, учтите, что uploadSourceMap() теперь возвращает Promise<void>. Чтобы дождаться загрузки перед следующим шагом сборки, используйте await или .then(). Обработчики onSuccess и onError сохранены; наличие onError не отменяет отклонение возвращённого Promise. Примеры приведены на странице Source Maps.
После обновления проверьте сбор ручных и необработанных ошибок, восстановление стеков по source maps, работу плагинов, ключей и контекста. Убедитесь, что модули не инициализируются повторно и продолжают работать после паузы. Если вы используете Performance, Web Vitals, Lite, Node.js или OpenTelemetry, проверьте их в средах, которые поддерживает ваше приложение.
Описание остальных настроек доступно в быстром старте.