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/