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

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

2021 年 9 月 15 日
筆記

系列

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

快速入門

前置條件

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

Step 1: 獲取程式碼

在 GitHub 上打開示例程式碼存儲庫
- //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 文檔中描述的步驟操作。
- //docs.sentry.io/product/releases/?platform=node/suspect-commits/
- //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 資訊。
- //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

//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：//docs.sentry.io/product/cli/

Sentry 目前支援與 GitHub、Bitbucket、Azure DevOps、GitLab 等的集成。有關我們集成的完整列表，請查看我們關於集成的文檔。

Integrations：//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 應用程式以觸發未處理的錯誤：//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 子句處理的異常。
要在您的本地主機上試用，請觸發以下端點：//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!")
```
要在您的本地主機上試用，請觸發以下端點：//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：//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 現在在標籤列表中可用（和可搜索）。

公眾號：黑客下午茶