# 无法 SSH 登录客户服务器时，如何调试应用

> 客户只说“坏了”，Sentry 能补上缺失的上下文，前提是配置时别把标签和上下文混为一谈。

原文: https://fdetimes.net/zh/tools/sentry-for-forward-deployed-engineers/

设想这样一个场景：晚上 10 点，客户发来消息：“订单审批页面又白屏了。”你登录不了他们的服务器，也不知道影响了哪些用户、从什么时候开始。修复速度主要取决于手头的上下文够不够，代码本身有多复杂，往往不是决定因素。

对前线部署工程师（FDE）来说，这是常态。你开发的应用跑在别人的环境里，出错时你不在现场，报告问题的人通常也不是工程师。Sentry 的作用，就是把这些上下文带回你的工位。

## Sentry 除了捕获异常，还能做什么？

Sentry 最初是一个开源项目。如今公司把自己的使命描述为：帮助每一位开发者诊断、修复并优化代码性能。关键词是“诊断”：捕获错误只是第一步，真正的价值在于 Sentry 如何组织这些错误。

最基本的单位是事件（event），即错误的一次发生。如果不加处理，500 个事件就是 500 行毫无头绪的记录。Sentry 用指纹（fingerprint）把相似事件归并为 issue，你能看到一个问题重复出现了多少次，从而决定先处理哪个错误。

每个 issue 都有一个 Issue Details 页面。Stack Trace 部分显示事件出错的那一行代码。面包屑（breadcrumbs）记录错误发生前的一系列事件，它们是结构化数据，携带的信息比传统日志更多。

## 三类上下文，三种用途

新手常把标签（tag）和上下文（context）混为一谈。在客户现场，一旦弄错，真到需要过滤的时候就过滤不了。下表总结了两者的区别：

| 数据类型 | 是什么 | 适用场景 |
|---|---|---|
| 标签 | 字符串键值对，会建索引，可搜索 | 需要过滤时：这个错误影响哪种浏览器、哪类设备、哪些用户？ |
| 上下文 | 一组用于辅助调试的相关数据，不可搜索 | 打开某个具体事件后，需要查看细节时 |
| 面包屑 | 错误发生前的事件时间线 | 需要知道用户或系统在出错前刚做了什么时 |

由此得出的规则很简单：凡是你会以“属于 X 类的错误有多少”这种方式提问的数据，放进标签；只在查看具体案例时才需要的数据，留在上下文里。

以 JavaScript SDK 为例，订单审批应用的最小配置大致如下（版本名和取值仅作示意）：

```js
Sentry.init({
  dsn: "<项目 DSN>",
  release: "order-approval@2.4.1",
  sampleRate: 1.0,
});

// 标签：之后需要按分支过滤
Sentry.setTag("branch_id", "new-branch-07");

// 上下文：只在打开具体事件时查看
Sentry.setContext("order", { orderId: "ORD-1024", status: "pending" });
```

两条注释分别是“标签：之后需要按分支过滤”和“上下文：只在打开具体事件时查看”。分支 ID 放在标签里，因为你迟早会问：“这个错误是不是只出现在某一个分支？”订单 ID 和订单状态放在上下文里，因为它们只在查看单个事件时才有用。`release` 这一行，会在下面案例的最后派上用场。

## 案例拆解：订单审批页面白屏

回到晚上 10 点那条消息。假设应用从一开始就接入了 Sentry。你打开控制台，看到一个新 issue，下面有几百个事件：几百次白屏被指纹归并成了同一个问题。这是一个反复出现的错误，而不是几百个不同的错误。

堆栈跟踪指向读取订单数据某个字段的那一行。面包屑显示，出错前用户先打开了筛选器，然后调用了获取订单列表的 API。你按 `branch_id` 标签过滤，发现错误只出现在一部分用户身上，比如刚接入系统的某个分支的用户。

最后一块拼图是版本（release）。在 Sentry 中，release 指部署到某个环境的一个代码版本。有了版本信息，Sentry 就能推测可能引发错误的提交，以及提交者。

如果这个 issue 之前已经解决过，又在新版本中重新出现，Sentry 会将其标记为回归（regression）。单凭这一点，你就知道是今天下午的部署把旧 bug 带了回来。

客户还没来得及再发一张截图，你已经能回答：哪里出错、哪一行代码、影响哪些用户、来自哪个版本。第一件事是告诉客户影响范围有多大，然后再修复。客户通常更急于听到“只有新分支受影响”，而不是马上拿到补丁。

**要点:** 只有把上下文带回自己的工位，才能快速修复客户系统上的错误。

## 在客户系统上容易出问题的地方

最大的风险是数据。面包屑和上下文越丰富，就越可能夹带终端用户的邮箱、手机号或 token。Sentry 可以在服务端存储数据之前清洗敏感信息。对于运行在客户系统内的应用，要在生产环境开启 Sentry 之前配置好这一项，而不是事后补救。

第二个陷阱是采样。默认情况下 SDK 会发送所有错误，因为错误采样率为 1。但事务（transaction）和链路追踪数据，不配置就不会发送。所以当客户抱怨“慢”而不是“坏了”时，默认安装根本拿不到任何性能数据。

第三个陷阱出现在客户要求本地部署时。Sentry 有自托管版本，但只是最小化部署，没有任何保障，也没有专门的支持团队。如果走这条路，要和客户明确约定由谁负责运维和升级，不要默认这件事归你。

Sentry 还提供 Seer，这是一个用于调试的 AI 智能体，会扫描新进的 issue，查找根因并自动完成分诊。issue 数量很多时，Seer 能帮上忙，但它只能利用你发送过去的上下文。没有标签和版本信息，任何智能体都只能靠猜。

## 先学什么，如何自测

合理的顺序是：先熟练阅读 Issue Details 页面，再给每次部署关联版本，然后为自己的业务领域设计一套标签，最后再处理数据清洗和链路追踪。每一步都可以花一个晚上在个人项目里试一试。

自测：针对上面的订单审批应用，判断以下五个字段该放在标签还是上下文里：用户角色（员工或经理）、浏览器、订单中的商品列表、环境（staging 或 production），以及获取订单列表的 API 的响应体。

参考答案：用户角色、浏览器和环境是标签，因为你会想问：“这个错误是不是只影响经理、只出现在某一种浏览器、只发生在生产环境？”

商品列表和 API 响应是上下文，因为它们只在查看单个事件时才有用。这两个字段也最容易混入敏感数据，因此必须经过数据清洗。

在个人项目里做过之后，就按实际做法写进简历。“为应用的错误监控设计了标签体系、版本追踪和 PII 数据清洗”这样一句话，远比“熟悉 Sentry”有分量。

在客户现场，上线之后，客户下一次想起你，通常是出了故障的时候。你是能立刻答出哪里出错、出在哪、属于哪个版本，还是得等客户再发截图，很大程度上取决于部署当天你是如何配置 Sentry 的。

**本周动手试试:**

- 在个人项目中安装 Sentry，故意触发一个错误，然后从堆栈跟踪到面包屑，完整读一遍 Issue Details 页面
- 给每次部署关联版本，解决一个 issue，再让这个错误在下一个版本中重现，观察 Sentry 如何标记回归
- 列出应用中的敏感字段（邮箱、手机号、token），并为它们配置数据清洗

## 信源

- [About Sentry | Sentry](https://sentry.io/about/)

- [Issues | Sentry Docs](https://docs.sentry.io/product/issues/)

- [Breadcrumbs (Browser JavaScript) | Sentry Docs](https://docs.sentry.io/platforms/javascript/enriching-events/breadcrumbs/)

- [Issue Details | Sentry Docs](https://docs.sentry.io/product/issues/issue-details/)

- [Releases | Sentry Docs](https://docs.sentry.io/product/releases/)

- [Data Scrubbing | Sentry Docs](https://docs.sentry.io/security-legal-pii/scrubbing/)

- [Sampling (Browser JavaScript) | Sentry Docs](https://docs.sentry.io/platforms/javascript/configuration/sampling/)

- [Seer | Sentry Docs](https://docs.sentry.io/product/ai-in-sentry/seer/)

- [Self-Hosted Sentry | Sentry Docs](https://develop.sentry.dev/self-hosted/)
