[[423947]]

目錄

• 快速開(kāi)始
  • 前置條件
  • Step 1: 獲取代碼
  • Step 2: 為您的存儲(chǔ)庫(kù)啟用提交跟蹤
  • Step 3: 安裝 SDK
  • Step 4: 安裝依賴(lài)項(xiàng) & 運(yùn)行 Demo App
• 配置選項(xiàng)
  • 發(fā)布版本(Releases)
  • 面包屑(Breadcrumbs)
  • 環(huán)境變量(Environment)
• 捕獲錯(cuò)誤
  • 捕獲 Exception
  • 捕獲 Message
  • 未處理的錯(cuò)誤
  • 處理的錯(cuò)誤
  • 增強(qiáng)事件數(shù)據(jù)

快速入門(mén)

前置條件

demo app 源代碼需要 Python 開(kāi)發(fā)環(huán)境來(lái)構(gòu)建安裝和運(yùn)行應(yīng)用程序。確保您已準(zhǔn)備好以下各項(xiàng)：

• https://www.npmjs.com/
• https://docs.sentry.io/product/cli/
• https://www.python.org/download/releases/3.0/
• https://code.visualstudio.com/
• 源代碼編輯器(如 VS-Code)
• Python3
• Sentry-CLI
• NPM

要開(kāi)始監(jiān)控應(yīng)用程序中的錯(cuò)誤，您需要在 Sentry 帳戶中創(chuàng)建一個(gè)新項(xiàng)目。請(qǐng)查看Sentry Web 前端監(jiān)控 - 最佳實(shí)踐(官方教程)以了解有關(guān)如何創(chuàng)建項(xiàng)目和定義警報(bào)規(guī)則的更多信息。

Step 1: 獲取代碼

在 GitHub 上打開(kāi)示例代碼存儲(chǔ)庫(kù)

https://github.com/sentry-tutorials/backend-monitoring

單擊 Fork 并選擇您希望將此存儲(chǔ)庫(kù)分叉到的目標(biāo) GitHub 帳戶

分叉完成后，單擊 Clone 或 download 并復(fù)制存儲(chǔ)庫(kù) HTTPS URL

 將分叉的存儲(chǔ)庫(kù)克隆到您的本地環(huán)境 

> git clone <repository HTTPS url> 

既然示例代碼在本地可用，請(qǐng)?jiān)谀走x的代碼編輯器中打開(kāi) backend-monitoring 項(xiàng)目

Step 2: 為您的存儲(chǔ)庫(kù)啟用提交跟蹤

Sentry 可以通過(guò)建議可能將錯(cuò)誤引入您的代碼庫(kù)的可疑提交來(lái)幫助您更快地解決錯(cuò)誤。這是通過(guò)配置提交跟蹤啟用的。需要集成您的源代碼管理解決方案并添加您的代碼存儲(chǔ)庫(kù)才能啟用提交跟蹤，有關(guān)更多信息，請(qǐng)參閱此鏈接。

打開(kāi)您的 Sentry 帳戶并導(dǎo)航到 Settings > Integrations 以啟用 GitHub 集成并添加您的 backend-monitoring 存儲(chǔ)庫(kù)。有關(guān)更多信息，請(qǐng)按照我們的 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 通過(guò)在應(yīng)用程序運(yùn)行時(shí)中使用特定于平臺(tái)的 SDK 來(lái)捕獲數(shù)據(jù)。要使用 SDK，請(qǐng)?jiān)谠创a中導(dǎo)入、初始化和配置它。

要開(kāi)始在我們的 Django 應(yīng)用程序中使用 SDK，我們通過(guò)在 requirements.txt 文件中定義依賴(lài)項(xiàng)來(lái)安裝 sentry-sdk。 Sentry SDK GitHub 存儲(chǔ)庫(kù)中提供了 SDK 文檔和 release 信息。

https://github.com/getsentry/sentry-python

打開(kāi) settings.py 文件(位于 ./backend-monitoring/myproject/settings.py 下)。這是我們?cè)趹?yīng)用程序中初始化和配置 Sentry SDK 的地方。

將 Sentry SDK 導(dǎo)入應(yīng)用程序后，導(dǎo)入 Sentry Django 集成也很重要。集成擴(kuò)展了 SDK 的一些常見(jiàn)框架和庫(kù)的功能。

import sentry_sdk 
 from sentry_sdk.integrations.django import DjangoIntegration 

在 Sentry SDK 配置中，輸入您從上一教程中創(chuàng)建的項(xiàng)目中復(fù)制的 dsn key。

sentry_sdk.init( 
    dsn="YOUR_DSN", 
    integrations=[DjangoIntegration()] 
) 

Step 4: 安裝依賴(lài)項(xiàng) & 運(yùn)行 Demo App

在 localhost 上構(gòu)建和運(yùn)行 Demo 應(yīng)用程序

打開(kāi) shell 終端并將目錄更改為 backend-monitoring 項(xiàng)目根文件夾

如果您尚未安裝 Python3，請(qǐng)運(yùn)行以下命令：

brew install python3 

安裝 virtualenv 和 virtualenvwrapper：

pip3 install virtualenv virtualenvwrapper 
echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc 
exec bash 

安裝 Sentry 的命令行工具以使用 release tracking 和 GitHub integration 來(lái)提交數(shù)據(jù)：

npm install -g @sentry/cli 

在項(xiàng)目根目錄中設(shè)置并激活 Python 3 虛擬環(huán)境。

mkvirtualenv --python=python3 sentry-demo-django 

您可以隨意命名 virtual environment，在我們的例子中，我們將其命名為 sentry-demo-django

要激活虛擬環(huán)境，請(qǐng)運(yùn)行：

workon sentry-demo-django 

打開(kāi)包含在項(xiàng)目根文件夾中的 Makefile。該文件在此處用于模擬 CI/CD 流程。

遵循 deploy 目標(biāo)執(zhí)行流程。

請(qǐng)注意，除了安裝 Python 要求和運(yùn)行服務(wù)器之外，我們還利用 sentry-cli 創(chuàng)建一個(gè)新的 Sentry Release，并將提交與該版本相關(guān)聯(lián)。在為您的項(xiàng)目問(wèn)題建議可疑提交時(shí)，Sentry 將查找這些提交。Makefile 中提到的命令將在下一部分配置選項(xiàng)中詳細(xì)解釋

要執(zhí)行 sentry-cli 命令，請(qǐng)按照此處描述的說(shuō)明獲取 SENTRY_AUTH_TOKEN、SENTRY_ORG 和 SENTRY_PROJECT 環(huán)境變量的值。

可以通過(guò)環(huán)境變量或?qū)Ｓ门渲梦募峁┻@些值來(lái)配置 sentry-cli。有關(guān)更多信息，請(qǐng)參閱 Sentry CLI > Configuration and Authentication

https://docs.sentry.io/product/cli/configuration/

運(yùn)行以下命令安裝所需的 Python 庫(kù)，設(shè)置 Sentry Release，并運(yùn)行 Django server：

make deploy 

在終端中，請(qǐng)注意創(chuàng)建了一個(gè)新 release 并且提交與其相關(guān)聯(lián)。部署成功完成后，您將在終端中看到確認(rèn)信息

配置選項(xiàng)

發(fā)布版本(Releases)

release 是部署到環(huán)境中的代碼版本。配置 Release 有助于您確定代碼中是否存在回歸(regression)、追究責(zé)任(hold accountability)、解決 Sentry 中的問(wèn)題(issues)以及與部署保持同步。 Releases 需要在您的 SDK 中進(jìn)行配置，然后通過(guò) sentry-cli 進(jìn)行管理以支持額外的功能，例如可疑提交(suspect commits)和建議的受理人(suggested assignee)。

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

Sentry 目前支持與 GitHub、Bitbucket、Azure DevOps、GitLab 等的集成。有關(guān)我們集成的完整列表，請(qǐng)查看我們關(guān)于集成的文檔。

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

讓我們看看我們?nèi)绾卧谶@個(gè)項(xiàng)目中設(shè)置 release：

打開(kāi)文件 settings.py。請(qǐng)注意，我們?cè)诔跏蓟?SDK 時(shí)添加了 release 配置選項(xiàng)。

release=os.environ.get("VERSION"), 

打開(kāi)您在上一教程中運(yùn)行的 Makefile。 

請(qǐng)注意，我們將 release version 名稱(chēng)設(shè)置為環(huán)境變量，然后在應(yīng)用程序的運(yùn)行時(shí)中使用。我們讓 CLI 建議 release version 名稱(chēng)，但您可能希望應(yīng)用您的命名約定：

VERSION=`sentry-cli releases propose-version` 

然后我們使用建議/選擇(proposed/selected)的名稱(chēng)為我們的項(xiàng)目創(chuàng)建新 release

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

在上一個(gè)教程中，我們配置了 GitHub 集成并添加了用于提交跟蹤的代碼存儲(chǔ)庫(kù)?，F(xiàn)在我們可以通過(guò)運(yùn)行以下命令將來(lái)自該存儲(chǔ)庫(kù)的提交與新版本相關(guān)聯(lián)：

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

面包屑(Breadcrumbs)

Breadcrumbs 是導(dǎo)致錯(cuò)誤的事件的蹤跡。在嘗試重現(xiàn)問(wèn)題時(shí)，它們非常有用。根據(jù)平臺(tái)，SDK 將默認(rèn)跟蹤各種類(lèi)型的面包屑(對(duì)于后端 SDK，這些是數(shù)據(jù)庫(kù)查詢(xún)、網(wǎng)絡(luò)事件、日志記錄等)，您也可以添加自定義面包屑。

讓我們看看如何將面包屑添加到我們的應(yīng)用程序中：

打開(kāi)文件 myapp > view.py

請(qǐng)注意，我們從 SDK 庫(kù)中導(dǎo)入了 add_breadcrumb。

from sentry_sdk import add_breadcrumb 

我們?yōu)橐晥D類(lèi)中的每個(gè)方法處理程序創(chuàng)建一個(gè)自定義面包屑。此面包屑將添加到與通過(guò)這些方法調(diào)用流觸發(fā)的任何錯(cuò)誤相關(guān)聯(lián)的面包屑軌跡中。例如，在 HandledErrorView:get 下：

add_breadcrumb( 
    category='URL Endpoints', 
    message='In the handled function', 
    level='info', 
) 

環(huán)境變量(Environment)

Environment 是一個(gè)強(qiáng)大的配置選項(xiàng)，它使開(kāi)發(fā)人員能夠使用 Sentry 在發(fā)生錯(cuò)誤的部署環(huán)境的上下文中執(zhí)行各種工作流(過(guò)濾問(wèn)題、觸發(fā)警報(bào)等)。

打開(kāi) settings.py 文件

請(qǐng)注意，我們使用環(huán)境配置選項(xiàng)初始化 SDK。SDK 將捕獲的任何事件都將使用配置的環(huán)境值進(jìn)行標(biāo)記。

environment:"Production" 

注意：Environment 值是自由格式的字符串。Sentry SDK 或 UI 不會(huì)限制您使用任何特定值或格式。在本例中，我們對(duì)值進(jìn)行了硬編碼。在現(xiàn)實(shí)生活中的應(yīng)用程序中，該值可能會(huì)通過(guò)屬性配置文件、系統(tǒng)或環(huán)境變量動(dòng)態(tài)確定。

捕獲錯(cuò)誤

未處理的錯(cuò)誤

Sentry SDK 將自動(dòng)捕獲并報(bào)告在您的應(yīng)用程序運(yùn)行時(shí)發(fā)生的任何未處理的錯(cuò)誤，無(wú)需任何額外配置或顯式處理。通常，未處理的錯(cuò)誤是沒(méi)有被任何 except(或 try/catch)子句捕獲的錯(cuò)誤。

在您的瀏覽器中，在以下端點(diǎn)中啟動(dòng)本地 Django 應(yīng)用程序以觸發(fā)未處理的錯(cuò)誤：http://localhost:8000/unhandled。

如果您設(shè)置了警報(bào)規(guī)則，您應(yīng)該會(huì)收到有關(guān)錯(cuò)誤的通知。否則，在您的 Sentry 帳戶中打開(kāi)問(wèn)題(Issues)視圖。

請(qǐng)注意未處理的異常出現(xiàn)在您的問(wèn)題流(Issues Stream)中。 

單擊 issue，打開(kāi) issue 詳細(xì)信息頁(yè)面。 

注意事件：

• 用我們?cè)谏弦唤坛讨性O(shè)置的 environment 和 release 選項(xiàng)進(jìn)行標(biāo)記并 handled:no - 將此事件標(biāo)記為未處理的錯(cuò)誤。
• 包含由我們之前啟用的提交跟蹤功能啟用的可疑提交(Suspect Commit)。
• 包含我們通過(guò) SDK 添加的自定義面包屑。

處理的錯(cuò)誤

Sentry SDK 包含多種方法，您可以利用這些方法在 except 子句、代碼的關(guān)鍵區(qū)域等中顯式(explicitly)報(bào)告錯(cuò)誤、事件和自定義消息。

捕獲 Exception

打開(kāi) views.py 文件。請(qǐng)注意，我們導(dǎo)入了包含 capture_exception 方法的 sentry_sdk 庫(kù)。

import sentry_sdk 

該方法用于捕獲由 HandledErrorView 中的 except 子句處理的異常。 

要在您的本地主機(jī)上試用，請(qǐng)觸發(fā)以下端點(diǎn)：http://localhost:8000/handled。

與未處理的錯(cuò)誤類(lèi)似，打開(kāi)新問(wèn)題(issue)的詳細(xì)信息頁(yè)面。

請(qǐng)注意，該事件使用相同的 environment 和 environment 配置選項(xiàng)進(jìn)行標(biāo)記。將鼠標(biāo)懸停在 release tag 中的 i 圖標(biāo)上以顯示 release 信息和與其關(guān)聯(lián)的提交。 

單擊 release 的 i 圖標(biāo)以導(dǎo)航到 release 頁(yè)面。

捕獲 Message

通常，不會(huì)發(fā)出 capture_message，但有時(shí)開(kāi)發(fā)人員可能希望在他們的應(yīng)用程序中添加一條簡(jiǎn)單的消息以進(jìn)行調(diào)試，而 capture_message 對(duì)此非常有用。

在 views.py 文件中， capture_message 方法通過(guò) sentry_sdk 庫(kù)導(dǎo)入提供。

您可以在應(yīng)用程序中的任何位置使用它。在我們的示例中，我們創(chuàng)建了一個(gè)專(zhuān)用的視圖類(lèi) CaptureMessageView 來(lái)觸發(fā)和捕獲我們想要跟蹤的消息

sentry_sdk.capture_message("You caught me!") 

要在您的本地主機(jī)上試用，請(qǐng)觸發(fā)以下端點(diǎn)：http://localhost:8000/message。

和以前一樣，從您的問(wèn)題流(Issues Stream)中打開(kāi)新問(wèn)題的詳細(xì)信息頁(yè)面。 

默認(rèn)情況下，捕獲的消息用嚴(yán)重(severity)級(jí)別標(biāo)記 level:info 標(biāo)記，如標(biāo)記部分所示。但是， capture_message 方法接受可選的嚴(yán)重性級(jí)別參數(shù)。

在 views.py 文件中，繼續(xù)將 capture_message 方法更改為：

sentry_sdk.capture_message("You caught me!", "fatal") 

保存更改并再次觸發(fā) /message 端點(diǎn)。(更改應(yīng)立即通過(guò) StateReloader 應(yīng)用)

請(qǐng)注意，新事件的嚴(yán)重性級(jí)別標(biāo)簽現(xiàn)在顯示 level:fatal。

增強(qiáng)事件數(shù)據(jù)

您可以通過(guò)添加自定義標(biāo)簽和用戶上下文屬性，通過(guò) Sentry SDK 豐富您的事件和錯(cuò)誤數(shù)據(jù)。除了為您的錯(cuò)誤提供更多上下文之外，這些還將擴(kuò)展您的選項(xiàng)以通過(guò)事件元數(shù)據(jù)進(jìn)行搜索、過(guò)濾和查詢(xún)。有關(guān)豐富數(shù)據(jù)的優(yōu)勢(shì)的更多信息，請(qǐng)參閱讓數(shù)據(jù)發(fā)揮作用。

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

讓我們用 capture_message 豐富我們捕獲的消息事件的數(shù)據(jù)。

在 views.py 文件中，找到觸發(fā) sentry_sdk.capture_message 的行。

用以下代碼替換該行：

with sentry_sdk.push_scope() as scope: 
scope.set_tag("my-tag", "my value") 
scope.user = { "email" : "my.email@your.domain.com" } 
scope.set_extra("someVariable", "some data") 
 
sentry_sdk.capture_message("You caught me!", "fatal") 

注意：我們正在使用 push_scope 方法，該方法允許我們?cè)诒镜胤秶鷥?nèi)發(fā)送具有一個(gè)特定事件的數(shù)據(jù)。我們?cè)诒镜胤秶鷥?nèi)設(shè)置自定義標(biāo)簽、用戶上下文屬性(電子郵件)和額外數(shù)據(jù)，以豐富消息事件的數(shù)據(jù)。

保存更改并再次觸發(fā) /message 端點(diǎn)。

從您的問(wèn)題流(Issues Stream)打開(kāi)問(wèn)題的詳細(xì)信息頁(yè)面。

請(qǐng)注意：

user email 現(xiàn)在顯示在詳細(xì)信息頁(yè)面上，受此事件影響的唯一用戶數(shù)反映在 issue 的標(biāo)題中。

custom tag 現(xiàn)在在標(biāo)簽列表中可用(和可搜索)。