Sentry 后端监控 - 最佳实践(官方教程)

系列

• 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 Web 前端监控 - 最佳实践(官方教程)

目录

• 快速开始
  • 前置条件
  • Step 1: 获取代码
  • Step 2: 为您的存储库启用提交跟踪
  • Step 3: 安装 SDK
  • Step 4: 安装依赖项 & 运行 Demo App
• 配置选项
  • 发布版本(Releases)
  • 面包屑(Breadcrumbs)
  • 环境变量(Environment)
• 捕获错误
  • 未处理的错误
  • 处理的错误
    • 捕获 Exception
    • 捕获 Message
  • 增强事件数据

快速入门

前置条件

1. 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/
2. 要开始监控应用程序中的错误，您需要在 Sentry 帐户中创建一个新项目。请查看Sentry Web 前端监控 - 最佳实践(官方教程)以了解有关如何创建项目和定义警报规则的更多信息。

Step 1: 获取代码

1. 在 GitHub 上打开示例代码存储库
   • https://github.com/sentry-tutorials/backend-monitoring
2. 单击 Fork 并选择您希望将此存储库分叉到的目标 GitHub 帐户
3. 分叉完成后，单击 Clone 或 download 并复制存储库 HTTPS URL

4. 将分叉的存储库克隆到您的本地环境

> git clone <repository HTTPS url>

5. 既然示例代码在本地可用，请在您首选的代码编辑器中打开 backend-monitoring 项目

Step 2: 为您的存储库启用提交跟踪

Sentry 可以通过建议可能将错误引入您的代码库的可疑提交来帮助您更快地解决错误。 这是通过配置提交跟踪启用的。 需要集成您的源代码管理解决方案并添加您的代码存储库才能启用提交跟踪，有关更多信息，请参阅此链接。

1. 打开您的 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，请在源代码中导入、初始化和配置它。

1. 要开始在我们的 Django 应用程序中使用 SDK，我们通过在 requirements.txt 文件中定义依赖项来安装 sentry-sdk。 Sentry SDK GitHub 存储库中提供了 SDK 文档和 release 信息。
   • https://github.com/getsentry/sentry-python
2. 打开 settings.py 文件（位于 ./backend-monitoring/myproject/settings.py 下）。 这是我们在应用程序中初始化和配置 Sentry SDK 的地方。
3. 将 Sentry SDK 导入应用程序后，导入 Sentry Django 集成也很重要。集成扩展了 SDK 的一些常见框架和库的功能。

    import sentry_sdk
    from sentry_sdk.integrations.django import DjangoIntegration
   

4. 在 Sentry SDK 配置中，输入您从上一教程中创建的项目中复制的 dsn key。

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

Step 4: 安装依赖项 & 运行 Demo App

在 localhost 上构建和运行 Demo 应用程序

1. 打开 shell 终端并将目录更改为 backend-monitoring 项目根文件夹

2. 如果您尚未安装 Python3，请运行以下命令：

   brew install python3
   

3. 安装 virtualenv 和 virtualenvwrapper：

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

4. 安装 Sentry 的命令行工具以使用 release tracking 和 GitHub integration 来提交数据：

   npm install -g @sentry/cli
   

5. 在项目根目录中设置并激活 Python 3 虚拟环境。

   mkvirtualenv --python=python3 sentry-demo-django
   

   您可以随意命名 virtual environment，在我们的例子中，我们将其命名为 sentry-demo-django

6. 要激活虚拟环境，请运行：

    workon sentry-demo-django
   

7. 打开包含在项目根文件夹中的 Makefile。 该文件在此处用于模拟 CI/CD 流程。

8. 遵循 deploy 目标执行流程。

   请注意，除了安装 Python 要求和运行服务器之外，我们还利用 sentry-cli 创建一个新的 Sentry Release，并将提交与该版本相关联。在为您的项目问题建议可疑提交时，Sentry 将查找这些提交。 Makefile 中提到的命令将在下一部分配置选项中详细解释

9. 要执行 sentry-cli 命令，请按照此处描述的说明获取 SENTRY_AUTH_TOKEN、SENTRY_ORG 和 SENTRY_PROJECT 环境变量的值。

   

   可以通过环境变量或专用配置文件提供这些值来配置 sentry-cli。 有关更多信息，请参阅 Sentry CLI > Configuration and Authentication

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

10. 运行以下命令安装所需的 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：

1. 打开文件 settings.py。请注意，我们在初始化 SDK 时添加了 release 配置选项。

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

2. 打开您在上一教程中运行的 Makefile。
   

3. 请注意，我们将 release version 名称设置为环境变量，然后在应用程序的运行时中使用。我们让 CLI 建议 release version 名称，但您可能希望应用您的命名约定：

   VERSION=`sentry-cli releases propose-version`
   

4. 然后我们使用建议/选择(proposed/selected)的名称为我们的项目创建新 release

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

5. 在上一个教程中，我们配置了 GitHub 集成并添加了用于提交跟踪的代码存储库。 现在我们可以通过运行以下命令将来自该存储库的提交与新版本相关联：

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

面包屑(Breadcrumbs)

Breadcrumbs 是导致错误的事件的踪迹。在尝试重现问题时，它们非常有用。 根据平台，SDK 将默认跟踪各种类型的面包屑（对于后端 SDK，这些是数据库查询、网络事件、日志记录等），您也可以添加自定义面包屑。

让我们看看如何将面包屑添加到我们的应用程序中：

1. 打开文件 myapp > view.py

2. 请注意，我们从 SDK 库中导入了 add_breadcrumb。

   from sentry_sdk import add_breadcrumb
   

3. 我们为视图类中的每个方法处理程序创建一个自定义面包屑。 此面包屑将添加到与通过这些方法调用流触发的任何错误相关联的面包屑轨迹中。 例如，在 HandledErrorView:get 下：

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

环境变量(Environment)

Environment 是一个强大的配置选项，它使开发人员能够使用 Sentry 在发生错误的部署环境的上下文中执行各种工作流（过滤问题、触发警报等）。

1. 打开 settings.py 文件
2. 请注意，我们使用环境配置选项初始化 SDK。SDK 将捕获的任何事件都将使用配置的环境值进行标记。

   environment:"Production"
   

   注意：Environment 值是自由格式的字符串。Sentry SDK 或 UI 不会限制您使用任何特定值或格式。在本例中，我们对值进行了硬编码。 在现实生活中的应用程序中，该值可能会通过属性配置文件、系统或环境变量动态确定。

捕获错误

未处理的错误

Sentry SDK 将自动捕获并报告在您的应用程序运行时发生的任何未处理的错误，无需任何额外配置或显式处理。 通常，未处理的错误是没有被任何 except（或 try/catch）子句捕获的错误。

1. 在您的浏览器中，在以下端点中启动本地 Django 应用程序以触发未处理的错误：http://localhost:8000/unhandled。

2. 如果您设置了警报规则，您应该会收到有关错误的通知。否则，在您的 Sentry 帐户中打开问题(Issues)视图。

3. 请注意未处理的异常出现在您的问题流(Issues Stream)中。
   

4. 单击 issue，打开 issue 详细信息页面。
   

5. 注意事件：

   • 用我们在上一教程中设置的 environment 和 release 选项进行标记并 handled:no - 将此事件标记为未处理的错误。
   • 包含由我们之前启用的提交跟踪功能启用的可疑提交(Suspect Commit)。
   • 包含我们通过 SDK 添加的自定义面包屑。
     

处理的错误

Sentry SDK 包含多种方法，您可以利用这些方法在 except 子句、代码的关键区域等中显式(explicitly)报告错误、事件和自定义消息。

捕获 Exception

1. 打开 views.py 文件。请注意，我们导入了包含 capture_exception 方法的 sentry_sdk 库。

   import sentry_sdk
   

2. 该方法用于捕获由 HandledErrorView 中的 except 子句处理的异常。
   

3. 要在您的本地主机上试用，请触发以下端点：http://localhost:8000/handled。

4. 与未处理的错误类似，打开新问题(issue)的详细信息页面。

5. 请注意，该事件使用相同的 environment 和 environment 配置选项进行标记。 将鼠标悬停在 release tag 中的 i 图标上以显示 release 信息和与其关联的提交。
   

6. 单击 release 的 i 图标以导航到 release 页面。

捕获 Message

通常，不会发出 capture_message，但有时开发人员可能希望在他们的应用程序中添加一条简单的消息以进行调试，而 capture_message 对此非常有用。

1. 在 views.py 文件中， capture_message 方法通过 sentry_sdk 库导入提供。

2. 您可以在应用程序中的任何位置使用它。 在我们的示例中，我们创建了一个专用的视图类 CaptureMessageView 来触发和捕获我们想要跟踪的消息

   sentry_sdk.capture_message("You caught me!")
   

3. 要在您的本地主机上试用，请触发以下端点：http://localhost:8000/message。

4. 和以前一样，从您的问题流(Issues Stream)中打开新问题的详细信息页面。
   

   默认情况下，捕获的消息用严重(severity)级别标记 level:info 标记，如标记部分所示。 但是， capture_message 方法接受可选的严重性级别参数。

5. 在 views.py 文件中，继续将 capture_message 方法更改为：

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

6. 保存更改并再次触发 /message 端点。（更改应立即通过 StateReloader 应用）

7. 请注意，新事件的严重性级别标签现在显示 level:fatal。

增强事件数据

您可以通过添加自定义标签和用户上下文属性，通过 Sentry SDK 丰富您的事件和错误数据。 除了为您的错误提供更多上下文之外，这些还将扩展您的选项以通过事件元数据进行搜索、过滤和查询。有关丰富数据的优势的更多信息，请参阅让数据发挥作用。

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

让我们用 capture_message 丰富我们捕获的消息事件的数据。

1. 在 views.py 文件中，找到触发 sentry_sdk.capture_message 的行。

2. 用以下代码替换该行：

   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 方法，该方法允许我们在本地范围内发送具有一个特定事件的数据。 我们在本地范围内设置自定义标签、用户上下文属性（电子邮件）和额外数据，以丰富消息事件的数据。

3. 保存更改并再次触发 /message 端点。

4. 从您的问题流(Issues Stream)打开问题的详细信息页面。

5. 请注意：

   • user email 现在显示在详细信息页面上，受此事件影响的唯一用户数反映在 issue 的标题中。
   • custom tag 现在在标签列表中可用（和可搜索）。

   

公众号：黑客下午茶