Sentry React Native监控

您已经拥有一个在本地工作的 React Native 应用程序，QA 已经批准了，生产即将到来。然后，一个明显的问题出现了：当它在用户设备上崩溃时会发生什么?

没有 Sentry，答案通常很糟糕。您会得到一个支持票，一个模糊的截图，可能是一个开发构建的控制台日志，它与生产构建不符。使用 Sentry React Native 进行正确的设置后，您会得到错误、堆栈、发布它的版本以及足够的上下文来修复它而不必猜测。问题在于 基本安装是容易的部分. native集成、符号化、源映射、发布命名以及在实时更新的交付模型中保持所有这些内容的对齐是痛苦的部分

大多数指南都太早停下来了。一个真正的设置必须能够承受CI、App Store构建、Android发布和JavaScript捆绑包，这些捆绑包并不总是来自原始二进制文件

使用Sentry进行SDK的入门
- 安装之前需要什么
- 运行向导并查看结果
配置Native iOS和Android项目
自动化发布和源映射
捕获性能数据和自定义事件
- 追踪慢屏幕而不是猜测
- 为错误添加有用的上下文
验证和调试您的集成
与 Capgo 类似Live Update工作流程集成
- 匹配发布标识符到实时包

Sentry SDK

快速开始 Sentry React Native

安装向导仍然是进入新应用程序的最快方法。它处理了大部分重复的设置，并快速让您达到工作基线。这种情况很重要，因为手动安装通常会导致您无法察觉的微小不匹配，直到第一个生产故障。

安装之前需要什么

您需要一个正常的 React Native 开发环境。 Node、一个包管理器、iOS 和 Android 的平台工具以及 macOS 上的 Watchman。如果您的工作流程中已经包含这些工具，则需要它们。您还需要一个 Sentry 帐户和一个为 React Native 创建的项目。如果您仍在评估 React Native 是否是您的团队的正确运营选择，这个关于 React Native 的企业指南

Install the SDK with the wizard from the project root:

npx @sentry/wizard@latest -i reactNative

从项目根目录使用向导安装 __CAPGO_KEEP_0__:

向导会问一些问题，开发人员经常快速点击通过:项目选择
选择您打算在生产中使用的实际 Sentry 项目，而不是您会忘记更新的临时沙盒。JavaScript-only 错误捕获并不能满足移动应用的需求。
可选功能启用你知道会使用的功能，但不要在团队未对结果数据进行审查的情况下启用所有功能。

运行向导并审查结果

向导完成后，请审查修改的代码，而不是简单地信任它们。您应该在 package.jsonnative 中看到修改 ios 和 android在

中看到初始化块。

import * as Sentry from '@sentry/react-native';

Sentry.init({
  dsn: 'YOUR_DSN',
});

典型的初始化代码如下： DSN 告诉SDK发送事件的位置。将其视为配置，而不是一个必须始终不可见的机密存储。它与认证令牌不同，但仍应保持环境设置的整洁和一致性，以便应用指向正确的Sentry项目。

A React Native 应用程序的实践模式是从环境特定的配置中加载 DSN，并在应用程序树的其余部分挂载之前初始化 Sentry。如果您还在优化启动过程中，这个指南到 React Native 启动屏幕设置 is useful because startup code order often intersects with where teams place Sentry initialization.

实践规则： 尽早在应用程序启动中初始化 Sentry。如果您等到导航、身份验证、远程配置之后，启动失败将会被忽略。

在这个阶段，不要追求完美。立即目标是简单的：启动应用程序，稍后在文章中触发 JavaScript 异常，并确认事件到达 Sentry。一旦这项工作正常，native 和发布层就变得更容易理解。

配置 Native iOS 和 Android 项目

At this stage, many React Native teams get a false sense of completion. The JavaScript SDK is installed, events show up, and everyone assumes crash reporting is done. It isn’t. If native integration is off, some of the crashes you care about most will never reach Sentry in a usable form.

iOS 中发生了什么变化

打开 iOS 项目并检查向导修改了什么。在一个裸露的 React Native 应用程序中，这通常意味着应用程序启动和构建阶段的更新。您正在寻找 Sentry 初始化钩子和与构建过程相关的上传步骤。

在 Xcode 中，检查这些地方：

App delegate startup code该应用程序需要在启动时尽早初始化本机 Sentry。
构建阶段查找与调试符号或源映射处理相关的 Sentry 上传脚本。
构建设置和存档行为符号文件必须在存档构建期间生成并可用。

如果您的应用程序使用 AppDelegate.mm，则初始化通常位于 React Native 桥启动引导的附近。具体文件内容可能因 React Native 版本、模板以及是否使用新架构而有所不同，因此请勿从随机仓库复制代码片段，除非它们与您的项目形状相匹配。

关键在于意图：iOS 本机崩溃需要符号数据，而应用程序必须在崩溃可靠观察之前启动 Sentry。

如果在 Sentry 中出现无法读取的本机帧的 iOS 崩溃问题，通常不是“Sentry 出现问题”。通常是符号上传或发布匹配的问题。

Android 中发生了什么变化

Android 通常在 Gradle 文件和 manifest 级别配置中添加更改。请检查 android/build.gradle, android/app/build.gradle，以及任何 Sentry 相关的插件或任务编排。

需要验证的内容：

已应用 Sentry Gradle 插件 因此，可以在构建时间处理发布 artifact。
变体处理是正常的 如果您使用产品风味或多个构建类型
如果您的发布构建缩小或混淆 __CAPGO_KEEP_0__，则已考虑 ProGuard 或 R8 输出 if your release builds shrink or obfuscate code.

移动构建类型的分解是一个有用的参考，用于保持监控行为与每个构建变体相对应。本地原生设置的检查可以节省时间

不要仅仅停留在“向导修改了文件”。直接验证行为

Don’t stop at “the wizard modified files.” Verify behavior directly.

使用以下检查清单：

在本地存档一个iOS构建 并确认在符号处理期间构建不会失败。
创建一个Android发布构建 并检查CI日志以查找与Sentry相关的任务。
检查包名和捆绑标识符映射 在Sentry中，如果您在一个组织下管理多个应用程序。
确认发布命名约定现在

在CI开始上传不一致名称下的艺术品之前。

以下通常不太有效：	方法
信任未经审查的魔法师	React Native 或构建工具发生变化时，原生设置会漂移
仅在调试模式下进行测试	调试成功掩盖了发布时符号化问题
混合手动和自动上传步骤	物件在不同发布中落地，无法匹配事件

最好的设置是无聊的。原生启动钩子已经设置，构建脚本每次都运行，iOS、Android 和 JavaScript 包的发布命名是确定的。

自动化发布和源码映射

如果有一个地方可以让 Sentry React Native 设置崩溃，那就是这里。团队安装了 SDK，看到事件，推迟了发布自动化。然后第一个严重的生产问题出现了，堆栈跟踪被压缩，发布缺失，或者源码映射上传属于不同的包。

手动源码映射上传听起来在你频繁发布时是可以接受的。在实践中，它们失败了，因为人类在重复的发布记录中很差。

为什么手动上传失败

失败模式是可预测的：

有人忘记上传地图 在深夜修复后。
上传的文件属于一个不同的提交 而用户运行的二进制或OTA包所对应的提交不同。
发布名称在iOS、Android和CI步骤之间会有所不同。 上传地图后会触发重新构建
这会使 Sentry 匹配的目标失效。 因此，我不建议采用“在 Notion 中记录步骤”的方法。它在紧急发布时会失效。

一张七步流程图，展示了管理 Sentry 发布和 React Native 源码地图的自动化流程。

一个能坚持的发布流程

可靠的设置有几个特点：

__CAPGO_KEEP_0__

Release ID会在第一次生成后 并在整个应用中重复使用。
构建、打包和上传步骤都在同一流水线中.
源映射从CI上传而不是从开发人员的笔记本电脑上传。
应用程序使用CI上传时使用的相同的发布字符串初始化Sentry。 上述最后一点比人们通常期望的更重要。您不仅需要在Sentry中包含源映射。您还需要

将正确的源映射附加到应用程序在运行时发出emit的确切发布标识符上 如果您的团队已经标准化了移动自动化，这份关于.

使用__CAPGO_KEEP_0__ Actions自动构建和发布工作流的指南 automatic build and release workflows with GitHub Actions __CAPGO_KEEP_0__

A实用CI脚本模式

在CI中使用类似这样的脚本，并从管道环境中获取值:

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

您需要为Android适配捆绑命令，并且许多团队将平台特定的工作分开，而不是强制一个脚本同时处理两者。这很好。关键是保持一致性。

发布纪律胜过聪明的脚本。 选择一个命名约定，注入它到构建时间，永远不要让本地临时上传与CI竞争。

对于React Native，我更喜欢将发布字符串存储在一个构建生成的配置位置，并在构建时读取它。 Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

好处很简单。当事件到达时，Sentry可以将最小化的帧映射回您实际发布的code，而不是您认为您发布的code。

捕获性能数据和自定义事件

崩溃告诉您什么东西出了问题。性能跟踪告诉您用户在什么时候感觉到慢了。

一个常见的报告听起来像这样：“仪表板很慢。”这不是足够的来调试。慢在哪里？在导航？在数据获取？在渲染一个重量级的图表？当您停止将Sentry视为错误收件箱并开始.instrument应用程序行为时，Sentry才会变得有用。

一名编码的软件开发人员坐在一台笔记本电脑上，背景监视器上显示数据可视化图表。

追踪一个慢的屏幕而不是猜测

首先在初始化中启用性能跟踪。具体采样策略取决于您的环境和容量容忍度，但结构如下:

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

如果您使用 React Navigation，需要将集成与屏幕转换关联起来，以便产生跟踪数据。然后在物理设备上重现抱怨，而不是仅在模拟器上。模拟器会隐藏用户注意到的那种缓慢性。

实用dashboard示例：

用户登录后打开主dashboard。
导航完成，但内容出现迟缓。
跟踪显示屏幕交易时间过长。
子span显示一个API请求和一个昂贵的渲染路径。
您优化渲染路径，重新发布，并比较新的跟踪形状。

这比凭直觉推断要好。

对于正在思考webview或混合应用监控模式的团队，这篇关于__CAPGO_KEEP_0__项目中的性能监控的文章 performance monitoring in Capacitor projects performance monitoring in __CAPGO_KEEP_0__ projects

添加有用的上下文到错误

性能数据在事件携带商业上下文时更有用。不是虚荣的元数据。只有足够的信息来回答谁受到了影响，用户在哪个屏幕上，什么在失败之前发生了。

使用这些工具有目的地：

用户上下文 与 Sentry.setUser() 这样支持人员可以将报告与受影响的帐户相关联，而不必在猜测中挖掘。
面包屑 用于像点击提交、打开模态或启动同步这样的操作。
自定义标签 用于维度如计划类型、特性标志状态或API区域。
捕获的异常与额外的上下文 当您捕获并重新抛出或表面受控失败时。

例子：

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

面包屑路径通常是区分“用户说应用程序冻结了”和“应用程序在打开仪表板、启动同步和重试过时请求后失败了”的关键因素。

当自定义指标出现问题时，它通常会因为过于噪音而出现问题。不要捕获应用程序中永远的按钮点击。捕获边界、状态转换和调试时重要的操作。足够的上下文来解释事件。不要让它淹没。

验证和调试您的集成

您应该在交付之前、在构建管道更改之后以及在SDK升级之后验证 Sentry。 “几个月前它工作了”并不是一个有意义的测试。

最干净的方法是触发 JavaScript 和本机路径的控制故障，然后检查它们如何在 Sentry 中到达。

一名男性软件开发人员坐在电脑监视器旁边，桌子上有一个测试集成清单，正在编写code。

安全触发测试事件

对于 JavaScript 错误，在非生产屏幕上添加一个临时按钮：

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

对于捕获的异常不会崩溃应用程序：

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

本机崩溃测试应该在开发或受控 QA 构建中小心进行。exact helper 方法可用性可能会根据SDK版本和平台编程而有所不同，所以我更喜欢使用SDK的文档化本机崩溃测试工具，而不是自己编写崩溃路径。

Sentry UI 中要检查的内容

当事件出现时，检查标题之外的更多内容。

检查这些字段：

平台和机制这有助于区分JS异常和本机崩溃。
发布和分发如果它们是空的或错误的，源映射和符号化将会偏离。
堆栈帧可读的源位置应该出现在正确上传的JavaScript映射中。
面包屑和标签确认您的自定义上下文已到达。
环境确保开发和生产事件不会混入一个流中。

如果原生事件到达但符号化很差，别再修改应用code。这通常是一个构建物品问题。

Sentry React Native 常见问题

症状	可能原因	解决方案
JavaScript 错误到达，但堆栈跟踪被压缩	源映射没有上传到匹配的发布	验证 CI 在打包后上传映射，并且 `release` 确保 `Sentry.init()` 与上传的发布完全匹配
原生崩溃不出现	原生SDK 钩子缺失或初始化太晚	重新检查iOS和Android原生设置，然后在QA构建中测试一个受控的原生崩溃路径
iOS原生帧不可读	调试符号未上传或未链接到正确的构建	确认存档构建生成符号并且上传步骤在CI或Xcode存档流程中运行
Android发布行为与调试行为不同	压缩或混淆会改变发布工件路径	查看发布Gradle任务并验证Sentry处理在发布变体中运行
事件出现在错误的环境下	构建时配置泄露到环境之间	分离DSN、环境、发布和dist值每个构建目标
面包屑或用户数据丢失	上下文设置太晚或在应用状态变化时清除	立即在认证状态解析后设置用户和标签，并在关键流程周围添加面包屑

最后形成良好的习惯是，在发布过程中保留一个微小的“监控烟雾测试”清单。在测试环境触发一个JS事件，确认发布值，并在发布之前验证源位置

与Capgo类似的Live Update工作流程

Live更新改变了发布模型。商店中的二进制文件可能保持不变，而JavaScript包在下面却会发生变化。如果 Sentry仍然只以原来的应用版本来思考，堆栈跟踪会很快变得误导性

解决方案是让 Sentry发布标识遵循live包而不是仅仅是原生的二进制文件

匹配发布标识到live包

对于Live Update工作流程，视 release 和 dist 作为与已交付的JavaScript包相关的运行时标识。原生的应用版本仍然很重要，但一旦包可以独立变化，它就不够了

一个实用的模式看起来像这样

使用原生应用版本作为基本发布名称的一部分。
附加实时更新版本或包标识符。
使用 dist 用于频道或构建特定区分时，适合您的模型。
上传每个实时包裹的源映射，具体使用该exact发布标识符。

例如，如果您的应用程序在启动时加载更新元数据，则使用当前活动包裹中派生的值初始化 Sentry，而不是仅从静态构建配置中派生值。

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

这样，当用户在热修复包中遇到错误时，Sentry 就会将帧解析为该热修复包的源映射，而不是较旧的商店包裹。

这与任何 OTA 风格的工作流有关。如果您想了解背后的移动部分的好入门指南，这个关于 __CAPGO_KEEP_0__ 应用程序中的实时更新工作原理的解释是一个坚实的参考。 how live updates work in Capacitor apps 截图来自 https://__CAPGO_KEEP_0__.app