Sentry Web 前端監控 - 最佳實踐(官方教程)

Sentry Web 前端監控 – 最佳實踐(官方教程)

2021 年 9 月 14 日
筆記

系列

創建一個 Sentry 項目
- Step 1: 創建項目
- Step 2: 創建警報規則
將 Sentry SDK 引入您的前端代碼
- 前置條件
- Step 1: 獲取代碼
- Step 2: 安裝 SDK
- Step 3: 安裝並運行 demo app
捕捉你的第一個錯誤
- Step 1: 捕捉你的第一個事件
- Step 2: 處理錯誤
在錯誤中啟用可讀堆棧跟蹤
- Step 1: 準備構建環境
- Step 2: 創建 release 並上傳 source maps
- Step 3: 嘗試您的更改 — 生成另一個錯誤
- Step 4: 探索 release
啟用可疑提交
- Step 1: 集成您的 GitHub 帳戶和存儲庫
- Step 2: 設置提交跟蹤
- Step 3: 可疑提交和建議受理人
- 更多信息

創建一個 Sentry 項目

Step 1: 創建項目

登錄您的 Sentry organization
- //sentry.io/
從左側導航菜單中選擇 Projects 以顯示所有項目的列表
單擊 + Create Project 按鈕

注意：如果您的帳戶中沒有項目 — 您可能會被重定向到入門嚮導以創建您的第一個項目。
- 根據您希望監控的代碼為您的項目選擇語言或框架——在本例中為 JavaScript。
- 給該項目一個 Name。
- 在 Set your default alert settings 下，選擇 i'll create my own alerts later。
- 為該項目分配一個 Team。
如果您尚未定義任何團隊(Team)，您可以選擇默認組織團隊（與您的 Sentry 組織同名的團隊）或單擊 + 按鈕創建新團隊。
- 單擊 Create Project。這會將您帶到配置頁面。通讀快速入門指南。
複製 DSN key 並將其放在手邊，因為我們會將密鑰複製到源代碼中。

DSN（或數據源名稱）告訴 SDK 將事件發送到何處，將它們與您剛剛創建的項目相關聯。

點擊 Got it! 按鈕以創建項目。

Step 2: 創建警報規則

您可以為每個項目創建各種警報規則，並讓 Sentry 知道您希望在應用程序中發生錯誤時通知的時間(when)、方式(how)和對象(whom)。警報規則(Alert rules)由條件(Conditions)和操作(Actions)組成，它們在滿足相關條件時執行。有關更多信息，請參閱 Alerts。創建新項目時，您可以選擇使用警報規則創建它，該規則在第一次出現新問題時通知所有項目團隊成員（通過電子郵件）。這意味着下次發生類似錯誤時，不會觸發通知，因為該錯誤不是「新的」。

//docs.sentry.io/product/alerts-notifications/alerts/

在此步驟中，您將創建一個新的 Alert 規則，在每次(every time)事件發生時發出通知，即使它與已經存在的問題相關聯。在實際的場景中，您可能會添加額外的條件，因為您不希望每次在終端用戶瀏覽器的前端代碼中發生事件時都得到通知。

從項目下拉列表中，找到新項目並點擊齒輪圖標打開項目設置(Project Settings)

單擊 Alerts 以打開警報配置頁面
單擊 New Alert Rule

在 「New Alert Rule」 表單中，選擇 「Issue Alert」 類型並輸入以下值

每次在所有環境(All Environments)中通過郵件(Mail)看到事件時，新的警報規則都會通知選定的團隊成員

單擊 Save Rule 以創建新規則

將 Sentry SDK 引入您的前端代碼

前置條件

Demo App 源代碼需要 NodeJS 開發環境來安裝和運行應用程序。確保您已準備好以下各項：

Node and NPM
- //nodejs.org/en/
NVM
- //github.com/nvm-sh/nvm

Step 1: 獲取代碼

在 GitHub 上打開 frontend-monitoring 示例代碼庫

//github.com/sentry-tutorials/frontend-monitoring

單擊 Fork 並選擇您希望將此存儲庫分叉到的目標 GitHub 帳戶

fork 完成後，單擊 Clone 或 download，然後複製存儲庫 HTTPS URL

將分叉的存儲庫克隆到您的本地環境

> git clone <repository HTTPS url>

現在示例代碼在本地可用，在您首選的代碼編輯器中打開 frontend-monitoring 項目

Step 2: 安裝 SDK

Sentry 通過在應用程序運行時中使用特定於平台的 SDK 來捕獲數據。要使用 SDK，請在源代碼中導入並配置它。 demo 項目使用 React 和 Browser JS。最快的入門方法是使用 JavaScript browser SDK 的 CDN 託管版本，但是，您也可以通過 NPM 安裝 browser SDK 。

//docs.sentry.io/platforms/javascript/install/npm/

打開 index.html 文件（位於 ./frontend-monitoring/public/ 下）

請注意，我們在代碼中儘可能早地導入和初始化 SDK。初始化 SDK 時，我們提供所需的配置。唯一的強制配置選項是 DSN key，但是，SDK 支持多個其他配置選項。有關更多信息，請參閱配置。

//docs.sentry.io/platforms/javascript/configuration/

在 Sentry SDK 配置中，輸入您從上一節創建的項目中複製的 DSN key 值。

Sentry.init({
  dsn: "<PASTE YOUR DSN KEY HERE>",
});

Step 3: 安裝並運行 demo app

在你的 localhost 上構建和運行 Demo 應用程序：

打開 shell 終端並將目錄更改為 frontend-monitoring 項目文件夾
使用 .nvmrc 文件設置與本項目兼容的 Node 版本。運行：

> nvm use

通過運行安裝項目依賴項：

> npm install

通過運行以下命令在 localhost 上構建、部署和運行項目：

> npm run deploy

部署成功完成後，您將在終端中看到確認信息。

捕捉你的第一個錯誤

Step 1: 捕捉你的第一個事件

通過在瀏覽器中打開 localhost 鏈接來啟動 demo app
- //localhost:5000/
打開瀏覽器的 Console 驗證是否發生了錯誤

點擊任何 Buy! 將產品添加到購物車的按鈕
單擊左側面板上的 Checkout 按鈕以生成錯誤

請注意：
- 應用程序中顯示出錯消息
- 錯誤出現在瀏覽器控制台中
- 發送到您在 Sentry 上配置的電子郵件地址的警報，通知您應用中發生的錯誤

Step 2: 處理錯誤

轉到您的電子郵件收件箱並打開 Sentry 的電子郵件通知
單擊 Sentry 上的查看以在您的 Sentry 帳戶中查看此錯誤的完整詳細信息和上下文
向下滾動到 Exception 堆棧跟蹤
- 請注意，堆棧跟蹤已 minified。JavaScript 通常被 minified 以減少源代碼的大小。
- Sentry 可以將代碼解壓縮(un-minify)回其可讀形式並在每個堆棧幀中顯示源（代碼）上下文行，這將在下一節中介紹。

在錯誤中啟用可讀堆棧跟蹤

Step 1: 準備構建環境

我們在 frontend-monitoring 項目中使用 Makefile 來利用 sentry-cli 處理與 Sentry 相關的任務。CLI 已通過項目依賴項（請參閱 package.json）提供，並且需要幾個參數才能運行。

打開 Makefile
取消注釋已注釋的環境變量 SENTRY_AUTH_TOKEN、 SENTRY_ORG 和 SENTRY_PROJECT （刪除前導 #）
查找 SENTRY_ORG 和 SENTRY_PROJECT 值
- 打開您的 Sentry 帳戶，然後單擊 Settings > Projects
- 您的 Organization ID 是瀏覽器 URL 的一部分（例如，//sentry.io/settings/SENTRY_ORG/projects/）
- SENTRY_PROJECT 值是出現在 project tile 中的名稱
- 複製值並將它們粘貼到 Makefile 中
創建 SENTRY_AUTH_TOKEN
- 單擊左側面板中的 Developer Settings 菜單選項名稱以創建新的集成(integration)和組織級(org-level)身份驗證令牌(auth token)
- 單擊 New Internal Integration
- 輸入 Name
- 在 Permissions 下設置 Release:Admin 和 Organization:Read & Write
- 單擊 Save Changes
- 保存成功確認後，向下滾動到頁面底部並複製 TOKENS 下分配的令牌
- 將令牌粘貼到 Makefile 中
Makefile 應如下所示：

Step 2: 創建 release 並上傳 source maps

現在我們可以調用 sentry-cli 來讓 Sentry 知道我們有一個新 release 並將項目的 source maps 上傳到它。

您可以設置自定義 release version 以適應您的命名約定，或者讓 Sentry CLI 建議一個版本。
為了構建 frontend-monitoring 項目，我們使用 react-scripts 包，它也在 ./build/static/js/ 下生成 source maps

在 Makefile 中，為 release version 添加一個新的環境變量，利用 Sentry CLI 提出版本值
```
REACT_APP_RELEASE_VERSION=`sentry-cli releases propose-version`
```
在 Makefile 的底部，使用 Sentry CLI 將以下目標粘貼到：
- 在您的 Sentry 帳戶中創建一個新的 release entity
- 將項目的 source maps 上傳到新 release
```
create_release:
sentry-cli releases -o $(SENTRY_ORG) new -p $(SENTRY_PROJECT) $(REACT_APP_RELEASE_VERSION)

upload_sourcemaps:
    sentry-cli releases -o $(SENTRY_ORG) -p $(SENTRY_PROJECT) files $(REACT_APP_RELEASE_VERSION) \
        upload-sourcemaps --url-prefix "~/static/js" --validate build/static/js
```
Makefile 包含一個 setup_release 目標，該目標在運行 $ npm run deploy 以構建和運行項目時從 package.json 文件中調用。我們將使用這個目標來調用所有與 release 相關的任務。
將現有的 setup_release 替換為：
```
setup_release: create_release upload_sourcemaps
```
您的 Makefile 應如下所示：

現在您創建了 release version，您可以通過 SDK 將應用中捕獲的任何錯誤與該 release 相關聯。
打開 index.html 文件並向 SDK 添加一個新的配置選項。
將 release version 環境變量分配給 release key
```
Sentry.init({
   dsn: "<YOUR DSN KEY>",
   release: "%REACT_APP_RELEASE_VERSION%",
 });
```
注意：release version 環境變量是在構建時在 project.json 中設置的，並被注入到生成的標記中。

Step 3: 嘗試您的更改 — 生成另一個錯誤

如果您的終端仍在 localhost 上提供 demo app，請單擊 ^C 關閉本地服務器
通過運行以下命令來構建、部署和重新運行項目：

> npm run deploy

注意：Makefile 在縮進方面通常是嚴格的。如果您在運行上述命令時遇到意外錯誤，請確保 sentry-cli 命令正確地以製表符(tab)為前綴。

查看終端日誌。請注意，minified 的腳本和 source maps 已上傳到 release version。
在您的瀏覽器中，確保開發控制台已打開並執行清空緩存和硬重新加載(Empty Cache and Hard Reload)以確保提供更新的代碼。
通過將產品添加到您的購物車並單擊 Checkout 再次生成錯誤
檢查您的電子郵件以獲取有關新錯誤的警報，然後單擊在 Sentry 上查看以打開 issue 頁面
請注意
- 該事件現在標記有 Release ID
- 錯誤堆棧跟蹤現在 un-minified，包括每個堆棧幀中的文件名、方法名、行號和列號以及源代碼上下文

Step 4: 探索 release

創建 release version 並通過 Sentry CLI 上傳 source maps，在您的 Sentry 帳戶中創建一個 Release entity。

單擊左側面板中的 Releases，注意創建了一個新的 release version
單擊 release，注意您的應用程序中的錯誤已與此 release 相關聯並列為New Issue
單擊 Artifacts 選項卡，注意 minified 的資源和 source maps 可用於此 release 並用於 source map 堆棧跟蹤

啟用可疑提交

Sentry 使用源代碼存儲庫中的提交元數據(metadata)來幫助您更快地解決問題。
這是通過建議可能在您的問題(issue)詳細信息頁面中引入錯誤的可疑提交(Suspect Commits)來完成的。
它還允許 Sentry 顯示 Suggested Assignees – 這些提交的作者列表並建議他們分配以解決問題(issue)。

現在您已經創建了一個 release，您可以告訴 Sentry 哪些提交與您的最新版本的代碼相關聯 —— 這稱為提交跟蹤(Commit Tracking)。

Step 1: 集成您的 GitHub 帳戶和存儲庫

要將 GitHub 與您的 Sentry 組織(org)集成，請按照 GitHub 文檔中的說明進行操作
- //docs.sentry.io/product/integrations/source-code-mgmt/github/
對於最後一步，從您的 GitHub 帳戶添加 frontend-monitoring 存儲庫

Step 2: 設置提交跟蹤

現在您已經在 Sentry 中設置了 releases 作為 CI/CD 流程的一部分並集成了源代碼存儲庫，您可以將鏈接存儲庫中的提交與發佈相關聯。

現在，您已經在 Sentry 中設置了 release 作為 CI/CD 流程的一部分，並集成了源代碼存儲庫，您可以將鏈接存儲庫中的 commits 與 releases 相關聯。

注意：在 demo 項目中，我們使用 Makefile 來處理與構建相關的任務。如果您沒有使用提供的 React demo 代碼並且沒有 Makefile，您可以選擇直接從命令行運行本教程中使用的 sentry-cli 命令，或者將這些命令集成到相關的構建腳本中。

在你的項目中打開 Makefile
在文件底部添加以下目標：

associate_commits:
    sentry-cli releases -o $(SENTRY_ORG) -p $(SENTRY_PROJECT) set-commits --auto $(REACT_APP_RELEASE_VERSION)

該命令將 commits 與 release 相關聯。 auto 標誌自動確定存儲庫名稱，並將前一個 release 的提交和當前主提交之間的提交與該 release 相關聯。

新的目標 associate_commits 將作為 setup_release 目標的一部分被調用，在最後添加它：

setup_release: create_release upload_sourcemaps associate_commits

您的 Makefile 應如下所示：

如果您的終端仍在 localhost 上提供 demo app，請按 ^C 將其關閉
通過運行以下命令在本地主機上構建、服務和重新啟動項目：

> npm run deploy

在終端日誌中，請注意 sentry-cli 標識了 GitHub 存儲庫。

Step 3: 可疑提交和建議受理人

現在可疑提交(suspect commits)和建議受理人(suggested assignees)應該開始出現在問題(issue)頁面上。Sentry 通過將 release 中的提交、這些提交涉及的文件、堆棧跟蹤中觀察到的文件、這些文件的作者和所有權規則聯繫在一起來確定這些。

刷新瀏覽器並通過將產品添加到購物車並單擊 Checkout 來生成錯誤
檢查您的電子郵件以獲取有關新錯誤的警報。請注意，電子郵件中添加了一個新的可疑提交(Suspect Commits)部分

單擊 Sentry 上的查看(View)以打開問題(issue)頁面
在主面板中，注意 SUSPECT COMMITS 部分現在指向最有可能引入錯誤的提交。您可以單擊提交(commit)按鈕在 GitHub 上查看實際提交詳細信息
在右側面板中的 Suggested Assignees — 您將看到可疑提交的作者被列為此問題的建議受理人(suggested assignee)

您可以通過單擊圖標將建議受理人分配給問題。但是，在這種情況下，提交源於上游存儲庫，並且建議受理人不是您組織的一部分。或者，您可以手動將問題分配給分配給項目的其他用戶或團隊。

單擊 Assignment 下拉列表並選擇一個項目用戶或團隊

在主面板中，找到 release 標籤並將鼠標懸停在 i 圖標上
在 release 彈出窗口中，注意 release 現在包含提交數據(commit data)

單擊 release i 圖標打開 release 詳細信息頁面
選擇 Commits 選項卡。請注意，release 現在包含相關的提交列表