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

系列

• 1 分鐘快速使用 Docker 上手最新版 Sentry-CLI - 建立版本
• 快速使用 Docker 上手 Sentry-CLI - 30 秒上手 Source Maps
• Sentry For React 完整接入詳解
• Sentry For Vue 完整接入詳解
• Sentry-CLI 使用詳解
• Sentry Web 效能監控 - Web Vitals
• Sentry Web 效能監控 - Metrics
• Sentry Web 效能監控 - Trends

目錄

• 建立一個 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: 建立專案

1. 登入您的 Sentry organization

   • https://sentry.io/

2. 從左側導航選單中選擇 Projects 以顯示所有專案的列表

3. 單擊 + Create Project 按鈕

   

   注意：如果您的帳戶中沒有專案 --- 您可能會被重定向到入門嚮導以建立您的第一個專案。

   • 根據您希望監控的程式碼為您的專案選擇語言或框架——在本例中為 JavaScript。
   • 給該專案一個 Name。
   • 在 Set your default alert settings 下，選擇 i'll create my own alerts later。
   • 為該專案分配一個 Team。

   

   如果您尚未定義任何團隊(Team)，您可以選擇預設組織團隊（與您的 Sentry 組織同名的團隊）或單擊 + 按鈕建立新團隊。

   

   • 單擊 Create Project。這會將您帶到配置頁面。通讀快速入門指南。

4. 複製 DSN key 並將其放在手邊，因為我們會將金鑰複製到原始碼中。

DSN（或資料來源名稱）告訴 SDK 將事件傳送到何處，將它們與您剛剛建立的專案相關聯。

1. 點選 Got it! 按鈕以建立專案。

Step 2: 建立警報規則

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

• https://docs.sentry.io/product/alerts-notifications/alerts/

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

1. 從專案下拉列表中，找到新專案並點選齒輪圖示開啟專案設定(Project Settings)

1. 單擊 Alerts 以開啟警報配置頁面

2. 單擊 New Alert Rule

1. 在 “New Alert Rule” 表單中，選擇 “Issue Alert” 型別並輸入以下值

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

1. 單擊 Save Rule 以建立新規則

將 Sentry SDK 引入您的前端程式碼

前置條件

Demo App 原始碼需要 NodeJS 開發環境來安裝和執行應用程式。確保您已準備好以下各項：

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

Step 1: 獲取程式碼

1. 在 GitHub 上開啟 frontend-monitoring 示例程式碼庫

• https://github.com/sentry-tutorials/frontend-monitoring

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

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

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

> git clone <repository HTTPS url>

1. 現在示例程式碼在本地可用，在您首選的程式碼編輯器中開啟 frontend-monitoring 專案

Step 2: 安裝 SDK

Sentry 通過在應用程式執行時中使用特定於平臺的 SDK 來捕獲資料。要使用 SDK，請在原始碼中匯入並配置它。 demo 專案使用 React 和 Browser JS。最快的入門方法是使用 JavaScript browser SDK 的 CDN 託管版本，但是，您也可以通過 NPM 安裝 browser SDK 。

• https://docs.sentry.io/platforms/javascript/install/npm/

1. 開啟 index.html 檔案（位於 ./frontend-monitoring/public/ 下）

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

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

1. 在 Sentry SDK 配置中，輸入您從上一節建立的專案中複製的 DSN key 值。

Sentry.init({

  dsn: "<PASTE YOUR DSN KEY HERE>",

});

Step 3: 安裝並執行 demo app

在你的 localhost 上構建和執行 Demo 應用程式：

1. 開啟 shell 終端並將目錄更改為 frontend-monitoring 專案資料夾

2. 使用 .nvmrc 檔案設定與本專案相容的 Node 版本。執行：

> nvm use

1. 通過執行安裝專案依賴項：

> npm install

1. 通過執行以下命令在 localhost 上構建、部署和執行專案：

> npm run deploy

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

捕捉你的第一個錯誤

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

1. 通過在瀏覽器中開啟 localhost 連結來啟動 demo app

   • http://localhost:5000/

2. 開啟瀏覽器的 Console 驗證是否發生了錯誤

1. 點選任何 Buy! 將產品新增到購物車的按鈕

2. 單擊左側面板上的 Checkout 按鈕以生成錯誤

   
   
   請注意：

   • 應用程式中顯示出錯訊息

   • 錯誤出現在瀏覽器控制檯中

   • 傳送到您在 Sentry 上配置的電子郵件地址的警報，通知您應用中發生的錯誤

     

Step 2: 處理錯誤

1. 轉到您的電子郵件收件箱並開啟 Sentry 的電子郵件通知

   

2. 單擊 Sentry 上的檢視以在您的 Sentry 帳戶中檢視此錯誤的完整詳細資訊和上下文

   

3. 向下滾動到 Exception 堆疊跟蹤

   

   • 請注意，堆疊跟蹤已 minified。JavaScript 通常被 minified 以減少原始碼的大小。
   • Sentry 可以將程式碼解壓縮(un-minify)回其可讀形式並在每個堆疊幀中顯示源（程式碼）上下文行，這將在下一節中介紹。

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

Step 1: 準備構建環境

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

1. 開啟 Makefile

2. 取消註釋已註釋的環境變數 SENTRY_AUTH_TOKEN、 SENTRY_ORG 和 SENTRY_PROJECT （刪除前導 #）

   

3. 查詢 SENTRY_ORG 和 SENTRY_PROJECT 值

   • 開啟您的 Sentry 帳戶，然後單擊 Settings > Projects

   • 您的 Organization ID 是瀏覽器 URL 的一部分（例如，https://sentry.io/settings/SENTRY_ORG/projects/）

   • SENTRY_PROJECT 值是出現在 project tile 中的名稱

     

   • 複製值並將它們貼上到 Makefile 中

4. 建立 SENTRY_AUTH_TOKEN

   • 單擊左側面板中的 Developer Settings 選單選項名稱以建立新的整合(integration)和組織級(org-level)身份驗證令牌(auth token)

   • 單擊 New Internal Integration

     

   • 輸入 Name

   • 在 Permissions 下設定 Release:Admin 和 Organization:Read & Write

     

   • 單擊 Save Changes

   • 儲存成功確認後，向下滾動到頁面底部並複製 TOKENS 下分配的令牌

     

   • 將令牌貼上到 Makefile 中

5. 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

1. 在 Makefile 中，為 release version 新增一個新的環境變數，利用 Sentry CLI 提出版本值

   REACT_APP_RELEASE_VERSION=`sentry-cli releases propose-version`
   
   

2. 在 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 相關的任務。

3. 將現有的 setup_release 替換為：

   setup_release: create_release upload_sourcemaps
   
   

   您的 Makefile 應如下所示：

   

   現在您建立了 release version，您可以通過 SDK 將應用中捕獲的任何錯誤與該 release 相關聯。

4. 開啟 index.html 檔案並向 SDK 新增一個新的配置選項。
   
   將 release version 環境變數分配給 release key

   Sentry.init({
   
      dsn: "<YOUR DSN KEY>",
   
      release: "%REACT_APP_RELEASE_VERSION%",
   
    });
   
   

   注意：release version 環境變數是在構建時在 project.json 中設定的，並被注入到生成的標記中。

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

1. 如果您的終端仍在 localhost 上提供 demo app，請單擊 ^C 關閉本地伺服器

2. 通過執行以下命令來構建、部署和重新執行專案：

> npm run deploy

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

1. 檢視終端日誌。請注意，minified 的指令碼和 source maps 已上傳到 release version。

   

2. 在您的瀏覽器中，確保開發控制檯已開啟並執行清空快取和硬重新載入(Empty Cache and Hard Reload)以確保提供更新的程式碼。

   

3. 通過將產品新增到您的購物車並單擊 Checkout 再次生成錯誤

4. 檢查您的電子郵件以獲取有關新錯誤的警報，然後單擊在 Sentry 上檢視以開啟 issue 頁面

5. 請注意

   • 該事件現在標記有 Release ID
   • 錯誤堆疊跟蹤現在 un-minified，包括每個堆疊幀中的檔名、方法名、行號和列號以及原始碼上下文

   

Step 4: 探索 release

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

1. 單擊左側面板中的 Releases，注意建立了一個新的 release version
   
   

2. 單擊 release，注意您的應用程式中的錯誤已與此 release 相關聯並列為New Issue
   
   

3. 單擊 Artifacts 選項卡，注意 minified 的資源和 source maps 可用於此 release 並用於 source map 堆疊跟蹤
   
   

啟用可疑提交

Sentry 使用原始碼儲存庫中的提交元資料(metadata)來幫助您更快地解決問題。

這是通過建議可能在您的問題(issue)詳細資訊頁面中引入錯誤的可疑提交(Suspect Commits)來完成的。

它還允許 Sentry 顯示 Suggested Assignees - 這些提交的作者列表並建議他們分配以解決問題(issue)。

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

Step 1: 整合您的 GitHub 帳戶和儲存庫

1. 要將 GitHub 與您的 Sentry 組織(org)整合，請按照 GitHub 文件中的說明進行操作

   • https://docs.sentry.io/product/integrations/source-code-mgmt/github/

2. 對於最後一步，從您的 GitHub 帳戶新增 frontend-monitoring 儲存庫

Step 2: 設定提交跟蹤

現在您已經在 Sentry 中設定了 releases 作為 CI/CD 流程的一部分並集成了原始碼儲存庫，您可以將連結儲存庫中的提交與釋出相關聯。

現在，您已經在 Sentry 中設定了 release 作為 CI/CD 流程的一部分，並集成了原始碼儲存庫，您可以將連結儲存庫中的 commits 與 releases 相關聯。

注意：在 demo 專案中，我們使用 Makefile 來處理與構建相關的任務。如果您沒有使用提供的 React demo 程式碼並且沒有 Makefile，您可以選擇直接從命令列執行本教程中使用的 sentry-cli 命令，或者將這些命令整合到相關的構建指令碼中。

1. 在你的專案中開啟 Makefile

2. 在檔案底部新增以下目標：

associate_commits:

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

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

1. 新的目標 associate_commits 將作為 setup_release 目標的一部分被呼叫，在最後新增它：

setup_release: create_release upload_sourcemaps associate_commits

您的 Makefile 應如下所示：

1. 如果您的終端仍在 localhost 上提供 demo app，請按 ^C 將其關閉

2. 通過執行以下命令在本地主機上構建、服務和重新啟動專案：

> npm run deploy

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

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

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

1. 重新整理瀏覽器並通過將產品新增到購物車並單擊 Checkout 來生成錯誤

2. 檢查您的電子郵件以獲取有關新錯誤的警報。請注意，電子郵件中添加了一個新的可疑提交(Suspect Commits)部分

1. 單擊 Sentry 上的檢視(View)以開啟問題(issue)頁面

2. 在主面板中，注意 SUSPECT COMMITS 部分現在指向最有可能引入錯誤的提交。您可以單擊提交(commit)按鈕在 GitHub 上檢視實際提交詳細資訊

3. 在右側面板中的 Suggested Assignees --- 您將看到可疑提交的作者被列為此問題的建議受理人(suggested assignee)

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

1. 單擊 Assignment 下拉列表並選擇一個專案使用者或團隊

1. 在主面板中，找到 release 標籤並將滑鼠懸停在 i 圖示上

2. 在 release 彈出視窗中，注意 release 現在包含提交資料(commit data)

1. 單擊 release i 圖示開啟 release 詳細資訊頁面

2. 選擇 Commits 選項卡。請注意，release 現在包含相關的提交列表

更多資訊

• 建立 Release 和關聯提交(Associate Commits)
  • https://docs.sentry.io/product/releases/setup/
• 全域性整合(Global Integrations)
  • https://docs.sentry.io/product/integrations/