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

系列

快速開始
- 前置條件
- Step 1: 獲取程式碼
- Step 2: 為您的儲存庫啟用提交跟蹤
- Step 3: 安裝 SDK
- Step 4: 安裝依賴項 & 執行 Demo App
配置選項
- 釋出版本(Releases)
- 麵包屑(Breadcrumbs)
- 環境變數(Environment)
捕獲錯誤
- 未處理的錯誤
- 處理的錯誤
  - 捕獲 Exception
  - 捕獲 Message
- 增強事件資料

快速入門

前置條件

demo app 原始碼需要 Python 開發環境來構建安裝和執行應用程式。確保您已準備好以下各項：
- 原始碼編輯器（如 VS-Code）
  - https://code.visualstudio.com/
- Python3
  - https://www.python.org/download/releases/3.0/
- Sentry-CLI
  - https://docs.sentry.io/product/cli/
- NPM
  - https://www.npmjs.com/
要開始監控應用程式中的錯誤，您需要在 Sentry 帳戶中建立一個新專案。請檢視Sentry Web 前端監控 - 最佳實踐(官方教程)以瞭解有關如何建立專案和定義警報規則的更多資訊。

Step 1: 獲取程式碼

在 GitHub 上開啟示例程式碼儲存庫
- https://github.com/sentry-tutorials/backend-monitoring
單擊 Fork 並選擇您希望將此儲存庫分叉到的目標 GitHub 帳戶
分叉完成後，單擊 Clone 或 download 並複製儲存庫 HTTPS URL

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

> git clone <repository HTTPS url>

既然示例程式碼在本地可用，請在您首選的程式碼編輯器中開啟 backend-monitoring 專案

Step 2: 為您的儲存庫啟用提交跟蹤

Sentry 可以通過建議可能將錯誤引入您的程式碼庫的可疑提交來幫助您更快地解決錯誤。這是通過配置提交跟蹤啟用的。需要整合您的原始碼管理解決方案並新增您的程式碼儲存庫才能啟用提交跟蹤，有關更多資訊，請參閱此連結。

開啟您的 Sentry 帳戶並導航到 Settings > Integrations 以啟用 GitHub 整合並新增您的 backend-monitoring 儲存庫。有關更多資訊，請按照我們的 GitHub 文件中描述的步驟操作。
- https://docs.sentry.io/product/releases/?platform=node/suspect-commits/
- https://docs.sentry.io/product/integrations/source-code-mgmt/github/

Step 3: 安裝 SDK

Sentry 通過在應用程式執行時中使用特定於平臺的 SDK 來捕獲資料。要使用 SDK，請在原始碼中匯入、初始化和配置它。

要開始在我們的 Django 應用程式中使用 SDK，我們通過在 requirements.txt 檔案中定義依賴項來安裝 sentry-sdk。 Sentry SDK GitHub 儲存庫中提供了 SDK 文件和 release 資訊。
- https://github.com/getsentry/sentry-python
開啟 settings.py 檔案（位於 ./backend-monitoring/myproject/settings.py 下）。這是我們在應用程式中初始化和配置 Sentry SDK 的地方。
將 Sentry SDK 匯入應用程式後，匯入 Sentry Django 整合也很重要。整合擴充套件了 SDK 的一些常見框架和庫的功能。
```
 import sentry_sdk

 from sentry_sdk.integrations.django import DjangoIntegration
```

在 Sentry SDK 配置中，輸入您從上一教程中建立的專案中複製的 dsn key。

sentry_sdk.init(

    dsn="YOUR_DSN",

    integrations=[DjangoIntegration()]

)

Step 4: 安裝依賴項 & 執行 Demo App

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

開啟 shell 終端並將目錄更改為 backend-monitoring 專案根資料夾
如果您尚未安裝 Python3，請執行以下命令：
```
brew install python3
```

安裝 virtualenv 和 virtualenvwrapper：

pip3 install virtualenv virtualenvwrapper

echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc

exec bash

安裝 Sentry 的命令列工具以使用 release tracking 和 GitHub integration 來提交資料：
```
npm install -g @sentry/cli
```
在專案根目錄中設定並激活 Python 3 虛擬環境。
```
mkvirtualenv --python=python3 sentry-demo-django
```
您可以隨意命名 virtual environment，在我們的例子中，我們將其命名為 sentry-demo-django
要啟用虛擬環境，請執行：
```
 workon sentry-demo-django
```
開啟包含在專案根資料夾中的 Makefile。該檔案在此處用於模擬 CI/CD 流程。
遵循 deploy 目標執行流程。

請注意，除了安裝 Python 要求和執行伺服器之外，我們還利用 sentry-cli 建立一個新的 Sentry Release，並將提交與該版本相關聯。在為您的專案問題建議可疑提交時，Sentry 將查詢這些提交。 Makefile 中提到的命令將在下一部分配置選項中詳細解釋
要執行 sentry-cli 命令，請按照此處描述的說明獲取 SENTRY_AUTH_TOKEN、SENTRY_ORG 和 SENTRY_PROJECT 環境變數的值。

可以通過環境變數或專用配置檔案提供這些值來配置 sentry-cli。有關更多資訊，請參閱 Sentry CLI > Configuration and Authentication

https://docs.sentry.io/product/cli/configuration/
執行以下命令安裝所需的 Python 庫，設定 Sentry Release，並執行 Django server：
```
make deploy
```
在終端中，請注意建立了一個新 release 並且提交與其相關聯。部署成功完成後，您將在終端中看到確認資訊

配置選項

釋出版本(Releases)

release 是部署到環境中的程式碼版本。配置 Release 有助於您確定程式碼中是否存在迴歸(regression)、追究責任(hold accountability)、解決 Sentry 中的問題(issues)以及與部署保持同步。 Releases 需要在您的 SDK 中進行配置，然後通過 sentry-cli 進行管理以支援額外的功能，例如可疑提交(suspect commits)和建議的受理人(suggested assignee)。

sentry-cli：https://docs.sentry.io/product/cli/

Sentry 目前支援與 GitHub、Bitbucket、Azure DevOps、GitLab 等的整合。有關我們整合的完整列表，請檢視我們關於整合的文件。

Integrations：https://docs.sentry.io/product/integrations/

讓我們看看我們如何在這個專案中設定 release：

開啟檔案 settings.py。請注意，我們在初始化 SDK 時添加了 release 配置選項。
```
release=os.environ.get("VERSION"),
```
開啟您在上一教程中執行的 Makefile。
請注意，我們將 release version 名稱設定為環境變數，然後在應用程式的執行時中使用。我們讓 CLI 建議 release version 名稱，但您可能希望應用您的命名約定：
```
VERSION=`sentry-cli releases propose-version`
```

然後我們使用建議/選擇(proposed/selected)的名稱為我們的專案建立新 release

> create_release:

sentry-cli releases -o $(SENTRY_ORG) new -p $(SENTRY_PROJECT) $(VERSION)

在上一個教程中，我們配置了 GitHub 整合並添加了用於提交跟蹤的程式碼儲存庫。現在我們可以通過執行以下命令將來自該儲存庫的提交與新版本相關聯：
```
> associate_commits:

  sentry-cli releases -o $(SENTRY_ORG) -p $(SENTRY_PROJECT) \

  set-commits $(VERSION) --auto
```

麵包屑(Breadcrumbs)

Breadcrumbs 是導致錯誤的事件的蹤跡。在嘗試重現問題時，它們非常有用。根據平臺，SDK 將預設跟蹤各種型別的麵包屑（對於後端 SDK，這些是資料庫查詢、網路事件、日誌記錄等），您也可以新增自定義麵包屑。

讓我們看看如何將麵包屑新增到我們的應用程式中：

開啟檔案 myapp > view.py
請注意，我們從 SDK 庫中匯入了 add_breadcrumb。
```
from sentry_sdk import add_breadcrumb
```
我們為檢視類中的每個方法處理程式建立一個自定義麵包屑。此麵包屑將新增到與通過這些方法呼叫流觸發的任何錯誤相關聯的麵包屑軌跡中。例如，在 HandledErrorView:get 下：
```
add_breadcrumb(

    category='URL Endpoints',

    message='In the handled function',

    level='info',

)
```

環境變數(Environment)

Environment 是一個強大的配置選項，它使開發人員能夠使用 Sentry 在發生錯誤的部署環境的上下文中執行各種工作流（過濾問題、觸發警報等）。

開啟 settings.py 檔案
請注意，我們使用環境配置選項初始化 SDK。SDK 將捕獲的任何事件都將使用配置的環境值進行標記。
```
environment:"Production"
```
注意：Environment 值是自由格式的字串。Sentry SDK 或 UI 不會限制您使用任何特定值或格式。在本例中，我們對值進行了硬編碼。在現實生活中的應用程式中，該值可能會通過屬性配置檔案、系統或環境變數動態確定。

捕獲錯誤

未處理的錯誤

Sentry SDK 將自動捕獲並報告在您的應用程式執行時發生的任何未處理的錯誤，無需任何額外配置或顯式處理。通常，未處理的錯誤是沒有被任何 except（或 try/catch）子句捕獲的錯誤。

在您的瀏覽器中，在以下端點中啟動本地 Django 應用程式以觸發未處理的錯誤：http://localhost:8000/unhandled。
如果您設定了警報規則，您應該會收到有關錯誤的通知。否則，在您的 Sentry 帳戶中開啟問題(Issues)檢視。
請注意未處理的異常出現在您的問題流(Issues Stream)中。
單擊 issue，開啟 issue 詳細資訊頁面。
注意事件：
- 用我們在上一教程中設定的 environment 和 release 選項進行標記並 handled:no - 將此事件標記為未處理的錯誤。
- 包含由我們之前啟用的提交跟蹤功能啟用的可疑提交(Suspect Commit)。
- 包含我們通過 SDK 新增的自定義麵包屑。

處理的錯誤

Sentry SDK 包含多種方法，您可以利用這些方法在 except 子句、程式碼的關鍵區域等中顯式(explicitly)報告錯誤、事件和自定義訊息。

捕獲 Exception

開啟 views.py 檔案。請注意，我們匯入了包含 capture_exception 方法的 sentry_sdk 庫。
```
import sentry_sdk
```
該方法用於捕獲由 HandledErrorView 中的 except 子句處理的異常。
要在您的本地主機上試用，請觸發以下端點：http://localhost:8000/handled。
與未處理的錯誤類似，開啟新問題(issue)的詳細資訊頁面。
請注意，該事件使用相同的 environment 和 environment 配置選項進行標記。將滑鼠懸停在 release tag 中的 i 圖示上以顯示 release 資訊和與其關聯的提交。
單擊 release 的 i 圖示以導航到 release 頁面。

捕獲 Message

通常，不會發出 capture_message，但有時開發人員可能希望在他們的應用程式中新增一條簡單的訊息以進行除錯，而 capture_message 對此非常有用。

在 views.py 檔案中， capture_message 方法通過 sentry_sdk 庫匯入提供。
您可以在應用程式中的任何位置使用它。在我們的示例中，我們建立了一個專用的檢視類 CaptureMessageView 來觸發和捕獲我們想要跟蹤的訊息
```
sentry_sdk.capture_message("You caught me!")
```
要在您的本地主機上試用，請觸發以下端點：http://localhost:8000/message。
和以前一樣，從您的問題流(Issues Stream)中開啟新問題的詳細資訊頁面。

預設情況下，捕獲的訊息用嚴重(severity)級別標記 level:info 標記，如標記部分所示。但是， capture_message 方法接受可選的嚴重性級別引數。
在 views.py 檔案中，繼續將 capture_message 方法更改為：
```
sentry_sdk.capture_message("You caught me!", "fatal")
```
儲存更改並再次觸發 /message 端點。（更改應立即通過 StateReloader 應用）
請注意，新事件的嚴重性級別標籤現在顯示 level:fatal。

增強事件資料

您可以通過新增自定義標籤和使用者上下文屬性，通過 Sentry SDK 豐富您的事件和錯誤資料。除了為您的錯誤提供更多上下文之外，這些還將擴充套件您的選項以通過事件元資料進行搜尋、過濾和查詢。有關豐富資料的優勢的更多資訊，請參閱讓資料發揮作用。

Put your Data to Work：https://docs.sentry.io/product/sentry-basics/guides/enrich-data/

讓我們用 capture_message 豐富我們捕獲的訊息事件的資料。

在 views.py 檔案中，找到觸發 sentry_sdk.capture_message 的行。
用以下程式碼替換該行：
```
with sentry_sdk.push_scope() as scope:

scope.set_tag("my-tag", "my value")

scope.user = { "email" : "[email protected]" }

scope.set_extra("someVariable", "some data")

sentry_sdk.capture_message("You caught me!", "fatal")
```
注意：我們正在使用 push_scope 方法，該方法允許我們在本地範圍內傳送具有一個特定事件的資料。我們在本地範圍內設定自定義標籤、使用者上下文屬性（電子郵件）和額外資料，以豐富訊息事件的資料。
儲存更改並再次觸發 /message 端點。
從您的問題流(Issues Stream)開啟問題的詳細資訊頁面。
請注意：
- user email 現在顯示在詳細資訊頁面上，受此事件影響的唯一使用者數反映在 issue 的標題中。
- custom tag 現在在標籤列表中可用（和可搜尋）。

公眾號：黑客下午茶

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