Добавление информации к событиям

Дополнительные ключи
JSON-контекст
ID пользователя
Окружение
Компонент
Идентификатор устройства
Логирование

В отчёте о браузерной ошибке доступны следующие сведения. SDK передаёт данные события, экрана и страницы; название и версию браузера, ОС и архитектуру сервер определяет по User-Agent. В Node.js состав полей отличается:

Параметр	Какую информацию предоставляет
`browserName`	Название браузера
`browserVersion`	Версия браузера
`documentVisibilityState`	Информация о видимости страницы в момент наступления ошибки
`errorEventType`	Тип события, спровоцировавшего ошибку (error, unhandledrejection и т.п.)
`host`	Хост, на котором была зарегистрирована ошибка
`osArchitecture`	Архитектура процессора устройства с ошибкой
`osFamily`	Операционная система устройства с ошибкой (Windows, Windows XP, iOS и т.п.)
`osVersion`	Версия операционной системы устройства с ошибкой
`screenHeight`/ `screenWidth`	Размеры экрана (`screen.width` / `screen.height`) в момент сбоя
`timestamp`	Отметка времени, в которое зафиксирован сбой
`tracerSdkVersion`	Используемая версия SDK
`userAgent`	User agent клиентского приложения

Вся полученная информация о событии отображена в разделе «Данные» на странице события:

К событиям можно добавить данные вашего приложения: ID пользователя, ключи, контекст и логи. Они помогут разобраться в причинах ошибки.

Возможности initTracerError

Дополнительные ключи

Добавляйте к ошибкам пары «ключ — значение», чтобы затем искать по ним события. Например, можно передать название эксперимента, адрес страницы или текущий раздел приложения.

Доступные опции:

Метод	Параметры	Описание
`setErrorKey()`	`key: string, value: string \| number \| boolean`	Добавляет пару ключ/значение ко всем отправляемым событиям.
`setErrorKeys()`	`keys: Record<string, string \| number \| boolean>`	Добавляет несколько пар ключ/значение.
`removeErrorKey()`	`key: string`	Сбрасывает ключ и соответствующие ему значения.
`removeErrorKeys()`	`keys: string[]`	Сбрасывает перечисленные ключи и соответствующие им значения.

SDK сохраняет ключи в памяти и добавляет их к новым событиям, пока вы не измените или не удалите эти ключи.

Пример использования

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

const tracerError = initTracerError();

// добавить key/value
tracerError.setErrorKey('someKey', 'someValue');
tracerError.setErrorKeys({
    someText: 'text',
    isTest: true,
});
// удалить один и несколько ключей
tracerError.removeErrorKey('isTest');
tracerError.removeErrorKeys(['someKey', 'someOtherKey']);

По ключам можно искать отчёты. Они отображаются в описании события:

Число и длина ключей ограничиваются сервером. В Tracer сохраняются до 30 пар; для отдельных проектов лимит может быть увеличен. Каждая пара передаётся как строка ключ=значение; ограничение 128 символов применяется ко всей строке, включая имя ключа и знак =. Сам SDK эти значения не сокращает.

JSON-контекст

К ошибке можно добавить JSON-контекст: например, ответ сервиса, состояние формы или параметры операции. Эти данные доступны при просмотре события. Если нужен поиск по значениям, используйте дополнительные ключи.

Общий контекст содержит именованные объекты, которые SDK добавляет к последующим ошибкам. Контекст в error(value, { context }) относится только к этому событию.

Метод	Параметры	Описание
`setErrorContext()`	`name: string, context: object`	Добавляет или заменяет общий объект или массив.
`setErrorContexts()`	`contexts: TracerErrorContext`	Добавляет или заменяет объекты и массивы по переданным именам, сохраняя остальные.
`removeErrorContext()`	`name: string`	Удаляет один общий объект из последующих ошибок.
`removeErrorContexts()`	`names: string[]`	Удаляет несколько общих объектов.

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

const tracerError = initTracerError();

tracerError.setErrorContext('screen', { name: 'checkout', step: 1 });
tracerError.setErrorContext('items', [{ id: 42, quantity: 2 }]);
tracerError.setErrorContexts({
    cart: { items: [{ sku: 'book', count: 2 }], coupon: null },
    experiment: { variant: 'B' },
});

tracerError.error(new Error('Не удалось оплатить'), {
    context: {
        screen: { name: 'payment' },
        response: { status: 503, retryable: true },
    },
});

tracerError.removeErrorContext('screen');
tracerError.removeErrorContexts(['cart', 'experiment', 'items']);

В этом примере к ошибке будут приложены cart, experiment, items, response и screen: { name: 'payment' }. Значение screen заменяется целиком, без объединения вложенных полей. Общий контекст при этом остаётся прежним.

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

Снимок объектов

SDK копирует собственные поля объектов, включая неперечислимые, а у Error — также name, message и stack. При копировании вызываются getter-ы и используется toJSON, если он есть. Содержимое Map и Set передавайте в виде обычного объекта или массива.

Циклические ссылки заменяются маркером [Circular], недоступные значения — [Unserializable]. Ошибка чтения отдельного поля не мешает сохранить остальные данные и саму ошибку.

Корень контекста — словарь. Значения именованного общего контекста должны быть объектами или массивами. Тип TracerErrorContext описывает входные данные; TracerJsonObject и TracerJsonValue — их JSON-копию, доступную фильтрам и плагинам. Некорректное обновление общего контекста сохраняет прежнее значение.

Ограничение размера

В конфигурации initTracerError() можно задать:

maxContextValueLength — длину каждого строкового значения. По умолчанию 750 единиц UTF-16, включая отметку сокращения ….
maxContextArrayLength — число сохраняемых элементов каждого массива. По умолчанию 100; остальные элементы отбрасываются.
maxContextDepth — число раскрываемых уровней, включая корень. По умолчанию 5; более глубокие объекты и массивы заменяются на [Object] и [Array].

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

На сервере контекст размером более 20 000 единиц UTF-16 сокращается; порог зависит от настроек сервера. Если контекст был отброшен, сама ошибка всё равно сохраняется.

ID пользователя

Передайте в userId тот идентификатор пользователя, который используется в вашем приложении. По нему можно найти все события этого пользователя.

Доступные опции:

Метод	Параметры	Описание
`setUserId()`	`id: string \| number`	Устанавливает userId.
`removeUserId()`	-	Сбрасывает текущее значение userId.

SDK сохраняет userId в памяти и добавляет его к новым событиям, пока вы не измените или не удалите идентификатор.

Пример использования

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

const tracerError = initTracerError();

tracerError.setUserId('123');    // устанавливает идентификатор
tracerError.removeUserId();      // сбрасывает идентификатор

Значение userId можно найти в разделе «Данные» в описании события – отсюда же возможно осуществить поиск по всем событиям этого пользователя.

Окружение

При инициализации initTracerErrorUploader и initTracerSessionUploader можно указать текущее окружение (например: dev/test/prod). Фильтр по данному параметру будет влиять на crash-free на графике аудитории – поэтому не забудьте указать этот параметр и при инициализации initTracerSessionUploader.

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

initTracerError();

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

initTracerErrorUploader(config);
initTracerSessionUploader(config);

Компонент

Если приложение состоит из нескольких компонентов, задайте имя компонента через setTracerComponentName(name). Tracer использует его для группировки ошибок и версий приложения. Настройка действует в основной версии SDK. Чтобы указать другой компонент для одной ошибки, передайте component в error(value, data).

Имя сохраняется в момент события: последующее изменение не переименует уже собранные ошибки. Настройка не влияет на экземпляры Lite.

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

setTracerComponentName('checkout');

Идентификатор устройства

getTracerDeviceId() возвращает идентификатор устройства, а setTracerDeviceId(uuid) позволяет задать его явно (строка UUID v4). Эти функции экспортируются из main. Идентификатор устройства отличается от ID пользователя и UUID сессии.

Возможности initTracerLog

Логирование

Логи помогают восстановить последовательность действий перед сбоем. Через initTracerLog можно записывать, например, переходы между страницами и действия пользователя. SDK хранит эти записи в памяти и прикладывает их к ошибкам.

Буфер логов хранится в памяти и рассчитан на 64 000 байт текста вместе с отметками времени и номерами записей. Старые строки вытесняются целиком. Последняя запись сохраняется даже при превышении этого объёма, поэтому размер отдельного сообщения ограничивайте в приложении.

Лог отправляется с каждой ошибкой. Чтобы в нём осталось место для полезных записей, сохраняйте только те действия, которые помогут разобраться в сбое.

Доступные опции:

Метод	Параметры	Описание
`log()`	`message: string`	Добавляет сообщение в лог
`clearLog()`	-	Очищает накопленный буфер логов.

Пример использования

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

const tracerLog = initTracerLog();
tracerLog.log('page: /settings');

SDK не собирает эти записи автоматически — вызывайте log() в тех местах приложения, которые хотите отслеживать.

Логи отображаются в соответствующем разделе отчёта об ошибке: