Sentry. Особенности подключения к Vue SPA

При подключении Sentry к backend, например, PHP Laravel, обычно не требуется внесения замысловатых настроек. Нужно установить пакет и прописать DSN. В случае же использования Sentry для отслеживания ошибок во frontend появляется ряд специфичных моментов. В этой статье будут собраны описания таких ситуаций и решения для них.

Table of Contents

• Базовые настройки Sentry
• DSN выносим в конфигурационный файл
• Привязка к релизу
• Карты исходного кода (source maps)
• Что дальше?

Базовые настройки Sentry

Базовые настройки совсем простые. Нужно установить пакет @sentry/vue:

npm install @sentry/vue

И подключить его в коде

const app = createApp({
  // ...
});

Sentry.init({
  app,
  dsn: '__PUBLIC_DSN__',
  integrations: [
    // Or omit `router` if you're not using vue-router
    Sentry.browserTracingIntegration({ router }),
  ],
});

Здесь сразу же подключена привязка к маршрутам (объекту router), чтобы в разделе Issues отображалось имя маршрута.

Есть и другие возможности Vue, которые поддерживаются Sentry. Об этом подробнее в документации к Sentry.

DSN выносим в конфигурационный файл

Предположим, что для dev-версии нам, не нужно, чтобы работал Sentry, или же для какого-то другого этапа разработки (stage) у нас другое значение DSN. Тогда можно вынести в конфигурационный файл .env переменную и читать значение в коде.

VITE_SENTRY_DSN=https://your-login-public-key-here@sentry.io/project-id

const sentryDsn = import.meta.env.VITE_SENTRY_DSN
if (sentryDsn) {
  Sentry.init({
    app,
    dsn: sentryDsn,
    integrations: [
      Sentry.browserTracingIntegration({ router }),
    ],
  })
} else {
  console.warn('VITE_SENTRY_DSN is not defined')
}

Привязка к релизу

В Sentry есть возможность привязать события к релизу. Когда мы сделали развертывание (deploy) новой версии, нам может быть интересно отследить не появляется ли наша ошибка в новом релизе. И вообще в каком релизе появилась ошибка. Тогда нам нужно указать параметр release

  Sentry.init({
    app,
    dsn: sentryDsn,
    release: import.meta.env.VITE_APP_RELEASE ?? 'unknown', // Указываем релиз
    integrations: [
      Sentry.browserTracingIntegration({ router }),
    ],
  })

Здесь, как можно заменить, мы читаем VITE_APP_RELEASE из переменных окружения. А значит нам нужно позаботиться о том, чтобы в процессе развертывания это значение было прописано. Например, наш скрипт развертывания мог бы писать имя релиза в файл .env.

Карты исходного кода (source maps)

При ознакомлении с деталями проблемы (issue) в Sentry может быть полезно просматривать путь выполнения кода (stack trace). Еще его часто называют стеком вызовов. Но в production, обычно, код минифицирован и его чтение человеком сильно затруднено.

Чтобы в этом блоке Sentry нам отобразился наш исходный код, а не минифицированная версия, нужно загрузить в Sentry карты исходного когда (source maps). При этом нам необходимо указать релиз в настройках, как указано выше.

Удобнее всего загружать карты исходного кода, пожалуй, через sentry cli. Нужно создать файл .sentryclirc с настройками подключения:

[defaults]
url = https://sentry.io/
org = my-org
project = my-project

[auth]
token = my-auth-token

В этом файле нужно указать правильные имена организации и проекта, а также значение токена. Его можно создать в настройках аккаунта, в подразделе Auth Keys. Токен должен иметь права org:read, project:read, project:write

Когда это сделано можно выполнять следующие команды:

npx sentry-cli releases new MY_RELEASE_NAME
npx sentry-cli releases files MY_RELEASE_NAME upload-sourcemaps dist --url-prefix '~/' --validate
npx sentry-cli releases finalize MY_RELEASE_NAME

Здесь

• MY_RELEASE_NAME — имя нашего релиза
• dist — папка, в которой находится собранная для production-версия приложения
• --url-prefix '~/' говорит Sentry, где искать файлы во время маппинга (обычно у Vue/Vite ~/ соответствует корню сайта)
• --validate проверяет, что файлы и sourcemaps корректные и совпадают

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

Теперь в Sentry, в разделе Releases можно выбрать любой релиз и посмотреть в нем наличие Source Maps. А самое главное — теперь путь выполнения кода в issue человекочитаем.

Что дальше?

Эта статья планировалась как регулярно обновляемая. Если появится новая полезная информация по интеграции Vue и Sentry, то сюда будет добавлен новый пункт.

Если у вас есть какие-либо заготовки на этот счет, то, пожалуйста, пишите о них в комментариях.