Как добавить Sentry в ваше приложение Vue.js и интегрировать его в GitLab CI/CD

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

Наши приложения для внешнего интерфейса написаны как на VueJS, так и на Angular и React, поэтому нам нужно было найти общий язык, чтобы легко поддерживать наш собственный конвейер CI/CD.

В этом руководстве мы рассмотрим все шаги, которые необходимо выполнить, чтобы настроить проект Vue.js для интеграции Sentry для отслеживания ошибок и производительности. Вы также узнаете, как правильно создавать выпуски Sentry и автоматически загружать исходную карту javascript/typescript, чтобы легко сопоставить транспилированный код с вашим исходным кодом.

Учебник по Angular и React будет выпущен в ближайшие недели, так что не волнуйтесь!

Вот список вещей, которые вам нужно сделать, чтобы достичь этого результата:

Установить Сентри
Инициализировать и настроить Sentry для отслеживания ошибок и производительности.
Импорт Sentry в жизненный цикл Vue.js
Обновите конвейер CI/CD
Бонус: отслеживать пользователя

Установить Сентри

Прежде всего, вам нужно создать новый проект Sentry, чтобы получить свое Имя источника данных (DSN). Думайте об этом как о своем идентификаторе проекта на Sentry.

Теперь вам нужно установить пакеты npm, необходимые для Sentry.

npm install --save @sentry/vue @sentry/tracing

Инициализировать и настроить Sentry для отслеживания ошибок и производительности.

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

Во-первых, как видите, мы используем множество переменных env. Вот пример нашего файла .env.production, используемого для производственной сборки.

NODE_ENV=production
VUE_APP_ENVIRONMENT=production
VUE_APP_API_URL=https://YOUR_WEBSITE_URL
VUE_APP_SENTRY_DSN=###REPLACE_WITH_YOUR_SENTRY_DSN###

Другие переменные env инициализируются в нашем vue.config.js, но вы можете напрямую загрузить эти значения прямо в файл sentry.ts.

Вот что вам нужно добавить к вашему vue.config.js

process.env.VUE_APP_NAME = require('./package.json').name;
process.env.VUE_APP_VERSION = require('./package.json').version;

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

Теперь давайте углубимся в настройку Sentry SDK:

среда: этот параметр указывает, в какой среде будет выпущено ваше приложение. Это позволит вам фильтровать производительность/ошибки на веб-сайте Sentry.
выпуск: здесь вы указываете название выпуска приложения. Релизы в Sentry должны быть уникальными для всей вашей организации. Вот почему мы используем такой шаблон, как app-name@version-number. Имя выпуска должно соответствовать тому же имени выпуска, которое используется в сценарии CI/CD, который создаст выпуск с вашими исходными картами.
dsn: это ваш уникальный идентификатор проекта Sentry. Он будет одинаковым для любой среды.
tracingSampleRate: это параметр производительности. Мы просто говорим, что в продакшне мы хотим отслеживать производительность только 25% всех сессий (1 = 100%).
trackComponents: включите этот параметр, если вы хотите также отслеживать дочерние компоненты и видеть более подробную информацию о процессе рендеринга.
logErrors: Sentry также будет вызывать функцию logError оригинального Vue, мы считаем, что эту опцию следует включать только в промежуточной среде.
attachProps: Sentry будет отправлять реквизиты всех компонентов Vue для регистрации.
attachStacktrace: трассировка стека автоматически прикрепляется ко всем зарегистрированным сообщениям.

Импорт Sentry в жизненный цикл Vue.js

Отлично, наш Sentry SDK был правильно инициализирован и настроен.

Если вам нужно настроить дополнительные параметры, вы можете ознакомиться непосредственно с официальным Руководством по Sentry для Vue. Мы только что поцарапали поверхность того, что вы можете с ним сделать.

Этот шаг действительно прост, нам просто нужно импортировать sentry.ts, чтобы правильно инициализировать Sentry SDK после того, как мы загрузили наше приложение Vue.

Так что просто откройте themain.ts вашего проекта Vue и давайте импортируем его.

import '@/sentry';

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

НО. Есть одна загвоздка! Все трассировки стека будут иметь транспилированный код, а не машинописный. И это большое нет-нет, потому что мы не могли легко понять, где проблема и как ее исправить. Без исходной карты, прикрепленной к нашему выпуску, это все равно, что пытаться читать запутанный код, и мы можем заверить вас, что это не очень приятное чувство.

Обновите конвейер CI/CD

Это сложная часть. Сделайте хороший глоток сваренного кофе, потому что вам действительно нужно сосредоточиться. Теперь мы собираемся автоматизировать процесс сборки, выпуска и развертывания в GitLab Pipeline.

Наш пайплайн будет разделен на три этапа:

build: где мы создаем наш проект Vue.
post-build: мы собираемся создать релиз Sentry и загрузить исходную карту.
deploy: где мы собираемся развернуть наш исходный код в нашей инфраструктуре AWS. Мы не будем объяснять этот шаг, но можем сказать, что внутри мы используем для этого AWS CDK. Наш стек представляет собой сочетание Route53, CloudFront и S3, как и любое приложение SPA, развернутое на AWS.

Прежде всего, нам нужно сгенерировать нашу сборку с исходными картами. Эти исходные карты (из соображений безопасности) не должны быть включены в ваш файл JavaScript. Нам просто нужно сгенерировать их, загрузить, а затем удалить перед развертыванием исходного кода.

Чтобы сгенерировать эту исходную карту, нам нужно отредактировать наш vue.config.js и указать Webpack сгенерировать исходную карту и показать их как «скрытые».

module.exports = {
 chainWebpack: (config) => {
  config.devtool(process.env.NODE_ENV === 'development' ? 'eval-source-map' : 'hidden-source-map')
 },
 css: {
  sourceMap: true
 },
}

Если вы хотите, вы можете взглянуть на документацию, чтобы узнать обо всех параметрах, которые предоставляет Webpack. В нашем случае как для staging, так и для production env мы используем параметры hidden-source-map:

То же, что и source-map, но не добавляет справочный комментарий к пакету. Полезно, если вы хотите, чтобы SourceMaps сопоставляли трассировки стека ошибок только из отчетов об ошибках, но не хотите предоставлять свою SourceMap для инструментов разработки браузера.

Следующий шаг — сообщить нашему конвейеру GitLab, что делать на каждом этапе.

Откройте свой .gitlab-ci.yml и настройте его следующим образом.

image: node:14
stages:
  - build
  - post-build
  - deploy
build-production:
  stage: build
  before_script:
    - npm config set prefix /usr/local
    - npm install
  script:
    - npm run buildwebsite:production
  artifacts:
    expire_in: 10 mins
    paths:
      - dist/
  only:
    - master
post-build-production:
  stage: post-build
  script:
    - npm install -g @sentry/cli --unsafe-perm
    - export PKG_NAME=$(node -p "require('${CI_PROJECT_DIR}/package.json').name")
    - export PKG_VERSION=$(node -p "require('${CI_PROJECT_DIR}/package.json').version")
    - export SENTRY_RELEASE_VERSION="${PKG_NAME}@${PKG_VERSION}"
    - export SENTRY_AUTH_TOKEN=$SENTRY_GIT_AUTH_TOKEN
    - export SENTRY_ORG=$SENTRY_GIT_ORG
    - export SENTRY_PROJECT=$SENTRY_GIT_PROJECT
    - echo "Create a new release $SENTRY_RELEASE_VERSION"
    - sentry-cli releases new $SENTRY_RELEASE_VERSION
    - sentry-cli releases set-commits --auto $SENTRY_RELEASE_VERSION
    - sentry-cli releases files $SENTRY_RELEASE_VERSION upload-sourcemaps $CI_PROJECT_DIR/dist
    - sentry-cli releases finalize $SENTRY_RELEASE_VERSION
    - echo "Finalized release for $SENTRY_RELEASE_VERSION"
  only:
    - master
deploy-production:
 stage: deploy
 before_script:
   - npm config set prefix /usr/local
   - npm install -g aws-cdk
   - npm install
 script:
   - rm $CI_PROJECT_DIR/dist/**/*.map || true
   - npm run buildcdk:production
   - npm run deploycdk:production
only:
   - master

Давайте сосредоточимся на каждом отдельном этапе, чтобы понять, что делает каждая команда. Я предполагаю, что у вас есть хотя бы минимальное понимание GitLab CI/CD.

Этап: сборка

На этом этапе мы собираемся построить наш SPA. buildwebsite:production — это просто псевдоним для этой команды vue-cli-service build. Это стандартная команда для создания рабочей версии вашего приложения Vue.

Эта команда создаст дистрибутив вашего приложения в папке /dist. В этой папке вы также найдете все .map файлов, содержащих исходные карты, которые нам нужно загрузить на Sentry.

Следующий важный шаг — сообщить GitLab, что мы хотим хранить на всех этапах артефакт, указывающий на нашу папку /dist. Этот артефакт будет временно доступен в течение следующих 10 минут, после чего он будет автоматически удален.

Пост-сборка сцены

На этом этапе мы создадим выпуск Sentry и загрузим исходную карту приложения, привязав их к этому конкретному выпуску.

Из Документации Sentry Release:

Выпуск – это версия вашего кода, развернутая в среде. Когда вы уведомляете Sentry о выпуске, вы можете легко определить новые проблемы, регрессии, решить проблему в следующем выпуске и применить исходные карты.

Релизы также предлагают значительные дополнительные функции при полной настройке Sentry SDK:

– Определите проблемы и регрессии, появившиеся в новом выпуске
– Предскажите, какая фиксация вызвала проблему и кто, вероятно, несет за нее ответственность
– Решите проблемы, включив номер проблемы в сообщение о фиксации
– Получение электронной почты уведомления, когда ваш код будет развернут

Чтобы использовать sentry-cli в своем пайплайне, вам нужно создать Токен авторизации на Sentry. Этот токен должен иметь следующие области действия:

проект: читать
проект:релизы
организация: читать

Следующее, что нужно сделать, это создать три переменные GitLab env для безопасного хранения токена и некоторой другой информации, которая потребуется в нашем конвейере. Итак, зайдите на страницу своего проекта GitLab и создайте эти переменные из Project > Settings > CI/CD > Variables. Нам нужно определить эти переменные:

SENTRY_GIT_PROJECT: оно должно иметь то же имя, что и имя вашего приложения, которое использовалось для создания выпуска.
SENTRY_GIT_ORG: в нем будет храниться слаг организации, который вы найдете в своем профиле организации Sentry. Это уникальный идентификатор, используемый для идентификации этой организации.
SENTRY_GIT_AUTH_TOKEN: в нем будет храниться значение токена аутентификации Sentry, который вы только что создали.

Отлично, теперь мы готовы настроить все необходимые нам локальные переменные, установить sentry-cli, создать релиз и загрузить исходные карты. Мы думаем, что эти команды CLI в значительной степени говорят сами за себя, но если вам нужны некоторые разъяснения, просто напишите нам несколько комментариев!

Стадия развертывания-производства

В этом разделе самое важное, что нам нужно сделать, это удалить те исходные карты, которые мы создали, потому что мы не хотим развертывать наш веб-сайт с общедоступными исходными картами.

Для того, чтобы их удалить, нужно просто сделать rm $CI_PROJECT_DIR/dist/**/*.map || true

buildcdk:production и deploycdk:production — это сценарии, которые просто создают наш конвейер CDK и развертывают наш веб-сайт, создавая или обновляя облачную формацию AWS.

Все процессы сборки CDK будут частью различных сообщений в блогах, которые будут опубликованы в ближайшие недели с полностью рабочим примером!

Бонус: отслеживать пользователя

Итак, теперь у нас есть все, что нам нужно, чтобы отслеживать нашу производительность и устранять все эти неприятные ошибки, как только они будут обнаружены Sentry. Следующим шагом является отслеживание (с согласия) сеанса пользователя, чтобы узнать, у кого возникла проблема.

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

Sentry.setUser({
	id: String(user.id),
	username: user.username,
	email: user.email,
});

Что дальше?

Оставайтесь с нами, потому что мы также собираемся выпустить одно и то же руководство для Angular и React!

Я надеюсь, что вам понравилась запись в блоге. Если вы хотите узнать больше о том, как мы работаем с интерфейсом, серверной частью и DevOps в Soplaya, просто подпишитесь на наш Soplaya TechBlog.