Crash, Non-Fatal and Crash-Free

• Инициализация модулей
• Конфигурация initTracerError
• Ручная регистрация ошибок
• Аудитория и crash-free
• Асинхронные стектрейсы

Трейсер предоставляет набор инструментов, которые позволяют отслеживать сбои типа CRASH (необработанные ошибки приложения) и вручную регистрировать некритические ошибки – NON_FATAL (даже если ошибка была обратана, имеет смысл зафиксировать её в сервисе). За сбор данных о событиях отвечает модуль initTracerError, а для отправки событий необходимо сконфигурировать initTracerErrorUploader (подробнее в Быстрый старт).

ВАЖНО! Трейсер хранит данные о событиях за последние 90 дней.

Для работы со сбоями приложения вам понадобятся следующие модули Tracer JS SDK:

Чтобы Tracer генерировал человекочитаемые стектрейсы, необходимо загрузить отладочную информацию (source maps). Подробнее о минификации JS-приложений читайте на странице Минификация (Source Maps)

Инициализация модулей

Для начала установите SDK – введите в терминале команду:

npm install @apptracer/sdk --save

Следите за актуальностью используемой версии, самая свежая – 2.6.3.

Проинициализировать SDK в проекте можно двумя способами:

• вариант 1: сконфигурировать необходимые модули отдельно друг от друга;
• вариант 2: проинициализировать единый объект SDK

В вашем app.js:

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

initTracerError({
    // ваши параметры
});

const config = {
    versionName: BUILD_VERSION_NAME,
    versionCode: BUILD_VERSION_CODE,
    appToken: 'appToken из настроек в Трейсере',
    environment: 'prod',
};

initTracerErrorUploader(config);
initTracerSessionUploader(config);

Конфигурация initTracerError

При базовой конфигурации Трейсер позволяет регистрировать и отправлять в сервис глобальные события – ошибки типов error и unhandledrejection. Однако можно сконфигурировать модуль более гибко под ваши предпочтения.

ВАЖНО! Конфигурация применится только при первой инициализации модуля. При повторных вызовах инстант не вернется. Для получения инстанса лучше пользоваться getTracerModules (подробнее).

filterError

Пример функции фильтрации ошибок на основне message зарегистрированной ошибки:

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

initTracerError({
    filterError: (error) => {
        if (error.message.indexOf('ignore error with this text') !== -1) {
            return false;
        }
    }
});

// ошибка не будет отправлена в Трейсер
throw new Error('ignore error with this text');

Ручная регистрация ошибок

Вы можете зарегистрировать обработанную ошибку в Tracer в качестве NON_FATAL – для этого воспользуйтесь методом initTracerError.error():

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

const tracerError = initTracerError();

try {
    JSON.parse('wrong json data');
} catch (e: any) {
    const error = e instanceof Error ? e : new Error('unknown error');

    tracerError.error(
        error,
        // можно передать дополнительные данные, если необходимо
        {
            keys: {
                url: location.href
            },
            userId: currentUserId,
            module: 'production',
            issueKey: 'special-request',    // подробнее см. ниже
        }
    );
}

В случае, если для ошибки нет стектрейса, информация по ней будет дополнительно браться из ErrorEvent

Дополнительная информация об ошибке

ITracerErrorInfo

Стандартный набор информации об ошибке содержит следующие данные:

Вместе с ошибкой вы можете передать дополнительную информацию о ней в качестве параметров:

Дополнительные флаги

Эти данные добавляются в информацию об ошибке автоматически:

issueKey

По умолчанию все сбои группируются по общим частям стектрейса, но в случае NON_FATAL может возникнуть необходимость выделить ошибку среди других аналогичных. Дело в том, что не всегда стектрейс и место, в котором залогировали ошибку, связаны между собой. Существует способ повлиять на эту группировку и собрать все NON_FATAL одного вида ошибки в одну группу при помощи специального ключа issueKey. Этот параметр также будет отображаться в названии события.

Преимущество issueKey в том, что не только вы сможете легко найти NON_FATAL, относящиеся к конкретной проблеме, но и другие разработчики смогут легко найти по ключу точку логирования этой ошибки (и удалить при необходимости) и отследить его в вашем issue-трекере.

Аудитория и crash-free

Для того, чтобы оценить надежность приложения и его способность сохранять работоспособность в течение продолжительного периода, Трейсер позволяет рассчитывать crash-free – процент пользователей, у которых не возникало сбоев в работе приложения за выбранный период. Отвечает за фичу модуль initTracerSessionUploader.

Рассчитывается метрика как (1 - (Пользователи со сбоем / Все пользователи)) * 100%. При этом важно понимать, что использование приложения на разных устройствах одного пользователя или переустановка приложения на текущем устройстве будут обозначены как самостоятельные единицы при расчётах. Отчёты о полученных Трейсером сбоях и графики по событиям можно найти в разделе «Сбои».

Перед использованием initTracerSessionUploader убедитесь, что в вашем проекте инициализирован initTracerError, иначе использование модуля будет бесполезно.

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

initTracerError();

initTracerSessionUploader({
    versionName: BUILD_VERSION_NAME,
    versionCode: BUILD_VERSION_CODE,
    appToken: 'appToken из настроек в Трейсере'
});

Подробнее о параметрах конфигурации Uploder-a ищите в Быстрый старт

Асинхронные стектрейсы

Часто возникают ситуации, когда ошибки случаются в асинхронном коде (например, во время обработки результатов запроса). В таких ошибках обычно очень мало информации, а потому непонятно, как мы к ней пришли (какой код вызвал данный запрос?). Модуль initTracerErrorAsyncStack позволяет дополнить стектрейс имеющейся ошибки.

Конфигурация initTracerErrorAsyncStack

Пример асинхронного стектрейса в небольшом демо: https://apptracer.ru/async-demo/

В вашем app.js:

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

initTracerErrorAsyncStack();
initTracerError();
initTracerErrorUploader({
    versionName: BUILD_VERSION_NAME,
    versionCode: BUILD_VERSION_CODE,
    appToken: 'appToken из настроек в Трейсере'
});

(function main() {
    setTimeout(function onTime() {
        Promise.resolve('wrong_json').then(data => {
            JSON.parse(data);
        });
    });
})();

В результате получаем ошибку с полной информацией о цепочке вызовов:

SyntaxError: Unexpected token 'w', "wrong_json" is not valid JSON
    at JSON.parse (<anonymous>)
    at https://apptracer.ru/async-demo/index.js:1:9543
(Promise.then onFulfilled)
    at https://apptracer.ru/async-demo/index.js:1:9529
(setTimeout)
    at HTMLButtonElement.main (https://apptracer.ru/async-demo/index.js:1:9476)