SuperAPI AI 工具集

crash-reporting-and-observability

部署与运维

查看项目

更新于 10-18 18:03

技能介绍

用途

该技能用于为 Expo 应用接入 Sentry 崩溃上报与可观测性,通过一个端口(CrashReporterPort)和一个适配器(sentry-crash-reporter-adapter.ts)实现,并作为根套件(root kit)插入到规范化的根骨架中。其目标是:在用户做出选择之前不发送任何数据,不发送任何个人身份信息,每个错误只到达一个 issue,每个商店构建和 OTA 更新都能在 TypeScript 源码中读取。

主要能力

  • 隐私优先:仅在 setConsent(true) 时启动 Sentry SDK;开发变体和空 DSN 永不启动;默认不采集 PII(sendDefaultPii: false),不启用截图、视图层级、Session Replay、反馈组件、日志或失败请求捕获。
  • 脱敏处理:beforeSend、beforeSendTransaction 和 beforeBreadcrumb 均调用 crash-scrubber.ts;不设置用户身份(仅 setUser(null)),端口无 setUser 成员。
  • 错误去重:保留 Hermes 的 rejection tracker,Sentry 保留全局处理器;根骨架的错误接收器本地记录所有错误,并通过 createCrashForwarder 仅转发 render 和 unhandled-rejection。
  • 面包屑规则:路由面包屑来自 useSegments()(如 tasks/[id]),不使用 usePathname() 或搜索参数;丢弃 console、触摸和 UI 面包屑;不使用 Sentry.wrap 或 TouchEventBoundary。
  • 发布与符号:release 和 dist 来自原生构建,environment 来自变体;Metro 使用 getSentryExpoConfig;每个 OTA 更新上传 source maps;上传令牌作为构建密钥存储在 EAS 或 CI 中。
  • 追踪默认关闭:TRACES_SAMPLE_RATE 和 PROFILES_SAMPLE_RATE 为字面量,上限由合同规定,无 tracesSampler。
  • 合同与声明:contracts/crash-reporting.json 记录事实,并与隐私声明同步。

使用方式

  1. 与开发者确认同意模型、是否开启追踪、上传配置和 org/project slug,填写 contracts/crash-reporting.json。
  2. 安装:npx expo install @sentry/react-native(不使用 @latest),保留可选依赖,重建开发客户端。
  3. 复制模板文件到指定路径(端口、适配器、脱敏器、转发器、假实现、根套件、配置、钩子、Metro 套件、Jest mock 等)。
  4. 在 src/services/create-root-kits.ts 中注册套件,根文件保持不变。
  5. 通过设置字段提供用户选择(crashReportsEnabled),默认遵循 consentModel;在设置行存在前使用 fixedCrashConsent(false)。
  6. 配置构建:Metro 套件使用 getSentryExpoConfig,插件条目包含 organization 和 project,非上报 profile 设置 SENTRY_DISABLE_AUTO_UPLOAD=true,每个 eas update 脚本追加 npx sentry-expo-upload-sourcemaps dist。
  7. 交接人工步骤:eas env:set 命令、Sentry 服务端脱敏设置、隐私与商店声明。
  8. 运行测试:npx jest src/services/crash-reporter src/hooks src/config scripts/metro --ci --maxWorkers=2,然后类型检查和 lint。
  9. 运行检查器:node ${CLAUDE_SKILL_DIR}/scripts/check-crash-reporting.mjs .,修复所有 FAIL 直到 RESULT: PASS。
  10. 首次商店发布前,在预览构建和命名模拟器/仿真器上进行设备验证。

适用场景

  • 需要合规、隐私优先的 Expo 应用崩溃监控接入。
  • 需要确保用户同意后才上报数据,且不采集 PII。
  • 需要每个构建和 OTA 更新都能正确符号化崩溃报告。
  • 需要避免重复上报和错误分类混乱。

限制

  • 仅适用于 Expo 应用,且依赖 Sentry 服务。
  • 需要开发者拥有 Sentry 账户并提供 org、project 和 DSN。
  • 需要遵循特定的文件结构和注册方式,不能直接粘贴 Sentry 官方设置片段。
  • 追踪默认关闭,开启需声明并受上限约束。
  • 部分步骤(如 EAS 变量设置、服务端脱敏)需人工完成。
  • 具体收费、价格、平台支持等细节暂未提供。