Документация
Спрятать
Создано в OK.TECH

С чего начать

Если для вашей платформы пока нет Tracer SDK, вы всё равно можете получать события в Tracer — для этого используется привычный Sentry SDK. Переписывать код приложения не нужно: Tracer принимает события по протоколу Sentry.

Чтобы направить события в Tracer через Sentry SDK,

Создание приложения через VK Cloud

Чтобы завести проект для платформы, у которой ещё нет Tracer SDK, используйте сервис VK Cloud — в нём создаются организация и проект в Tracer, и вы сможете получить параметры для подключения, в том числе Sentry DSN.

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

После подключения вы получите ссылку, направляющую вас напрямую в Tracer.

Доступные платформы

Sentry SDK можно использовать с Tracer на любой платформе, которую поддерживает Sentry.

Для части платформ у Tracer есть собственный SDK — на них вы можете выбрать, что подключать: Tracer SDK или Sentry SDK. Если для вашей платформы есть Tracer SDK, мы рекомендуем подключать именно его. Tracer SDK сейчас доступен для:

Для остальных платформ Tracer SDK пока нет — на них получать события в Tracer можно с помощью Sentry SDK. Например:

  • Java
  • Go
  • Python
  • C/C++ (Windows, Linux, macOS)
  • PHP
  • Perl
  • Ruby
  • C#

ВАЖНО! Если вам нужна поддержка других платформ, напишите в чат [Tracer] Feedback.

Как направить события в Tracer

Tracer принимает события по протоколу Sentry, поэтому в Sentry SDK достаточно изменить только адрес отправки — остальной код менять не нужно.

  1. В настройках Tracer перейдите на вкладку Проект. Из раздела API скопируйте Sentry DSN (Data Source Name):
  1. Передайте скопированный Sentry DSN в Sentry SDK — так же, как вы указывали DSN в своём проекте Sentry. Например, так.

После этого события вашего приложения начнут приходить в Tracer.

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

Детали использования Sentry SDK с Tracer

Как отправлять события и в Sentry, и в Tracer

Если вы хотите переходить на Tracer постепенно, можно какое-то время дублировать события: оставить отправку в Sentry и параллельно направлять тот же поток событий в Tracer.

Для этого:

  • настройте прокси, который будет зеркалировать трафик Sentry SDK и дополнительно отправлять копию событий в Tracer;
  • напишите команде Tracer в чат [Tracer] Feedback — мы настроим приём событий по вашему Sentry DSN.

Так вы сможете сравнить данные в обоих сервисах, прежде чем полностью переключиться на Tracer.

Как загружать сорсмапы

Вы можете загружать сорсмапы, символы или маппинги в Tracer, даже если используете Sentry SDK.

Посмотрите:

Как загружать сорсмапы для JavaScript-приложений

Посмотрите пример загрузки сорсмап для JavaScript-приложений — обратите внимание на особенности, которые важно учитывать при загрузке.

В настройках Sentry SDK укажите:

  • правильный Sentry DSN — его можно найти в разделе "Настройки" для вашего проекта в Tracer;
  • номер версии (релиза) приложения — должен совпадать в настройках Sentry SDK и в скрипте отправки архива с сорсмапами (см. ниже).

ВАЖНО!
Sentry SDK передаёт версию в поле release. Значение передаётся в произвольном формате, но если вы следуете рекомендациям Sentry и формируете release следующим образом:
<application>@<version>, то при обработке события сбоя Tracer отбросит всё до последнего символа @ включительно.
Tracer сопоставляет сорсмапы по пути (имени файла), а не по Debug ID, как в Sentry, поэтому при расхождении путей десимволизация не применится.
При работе с Tracer рекомендуется использовать semantic versioning.

Посмотрите пример настройки Sentry SDK

import * as Sentry from "@sentry/browser";

Sentry.init({
    dsn: "sentry-dsn-from-tracer-settings", // Sentry DSN — см. в разделе "Настройки" в Tracer.
    integrations: [
        Sentry.browserTracingIntegration(),
        Sentry.replayIntegration(),
    ],
    release: "1.0.0", // Номер версии — должен совпадать с тем, который будет указан при отправке сорсмап.
    tracesSampleRate: 1.0,
    replaysSessionSampleRate: 0.1
});

// Тестовая ошибка
const btn = document.getElementById('errorBtn');

btn.addEventListener('click', () => {
  // TypeError: Cannot read property 'click' of null
  const element = document.getElementById('missing');
  element.click();
});

При подготовке сорсмап к отправке обратите внимание на структуру папок.

Посмотрите пример создания архива с сорсмапами

Отправьте архив с сорсмапами в Tracer, указав pluginToken — его можно найти в разделе "Настройки" для вашего проекта в Tracer. Посмотрите варианты отправки.

Посмотрите пример отправки архива с сорсмапами

curl \
    -F sourcemapToken=<pluginToken> \ // `pluginToken` вашего проекта — см. в разделе "Настройки" в Tracer.
    -F "versionName=1.0.0"\ // Номер версии — должен совпадать с тем, который указан в настройках Sentry SDK.
    -F "file=@assets.zip" \
    https://plugin-api.apptracer.ru/api/sourcemap/upload

Если сорсмапы отправлены успешно, вы увидите вывод: {"success":true}.
После этого подождите несколько минут (сорсмапы загружаются в Tracer не мгновенно).

Запустите тестовое приложение и отправьте ошибку в Tracer. Вы увидите, что благодаря сорсмапам стектрейс стал человекочитаемым.

ВАЖНО!
Сорсмапы повлияют только на ошибки, которые будут отправлены после загрузки сорсмап.

Посмотрите пример стектрейса ДО загрузки сорсмап

Посмотрите пример стектрейса ПОСЛЕ загрузки сорсмап

Специальные возможности для пользователей Sentry SDK

Некоторые возможности были добавлены в Tracer специально для пользователей Sentry SDK, чтобы упростить миграцию. Позже эти функции станут доступны и пользователям Tracer SDK.

Breadcrumbs

Breadcrumbs из Sentry отображаются в Tracer в виде строки:

#номер_лога время | category | type | ...

Breadcrumbs можно найти в Tracer в разделе "События" > "Логи".

Сontext и Extra

Информация, которая передаётся с помощью setContext в Sentry, в Tracer отображается в разделе "События" > "Данные" > "Context".

В "Context" также отображаются данные Extra.