跳到主要内容

生产错误可观测性

让 a.js:1:4523 再次有用

通过上传源映射、同源 Sentry 隧道、带上下文的错误、过滤和会话回放，让生产故障变得可处理。

阅读时间：4分钟作者

所有文章

丢失故障的两种方式

我们有两个独立的盲区。由于缺少源映射，已收到的错误只指向 a.js:1:4523 等压缩代码；另一些事件则因为对 sentry.io 的直接请求被拦截而根本没有抵达。

这是两个独立故障。源映射决定已收到的堆栈能否还原符号；传输路径决定事件能否抵达 Sentry。只修复其中一个，事件仍可能无法阅读或完全不可见。

上传源映射，但不要公开提供

@sentry/nextjs 使用 withSentryConfig 包装构建。CI 提供 SENTRY_AUTH_TOKEN、SENTRY_ORG 和 SENTRY_PROJECT。构建插件上传源映射，扩大客户端文件上传范围以提供更完整的跟踪，并使用 deleteSourcemapsAfterUpload 防止这些映射出现在公共输出中。

export default withSentryConfig(nextConfig, {
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  authToken: process.env.SENTRY_AUTH_TOKEN,
  sourcemaps: {
    disable: process.env.NODE_ENV === 'development',
    deleteSourcemapsAfterUpload: true
  },
  widenClientFileUpload: true,
  disableLogger: true,
  tunnelRoute: '/t'
})

这样，符号还原便包含在正常的部署构建中，不需要工程师在发布后记得单独运行 sentry-cli 上传命令。

通过应用的同源端点传输事件

最初的同源端点是 /monitoring，但拦截器仍会匹配它。我把路由缩短为 /t。之后，浏览器事件发送到应用来源，再由 Next.js 服务器转发给 Sentry。

原始发布记录显示，更改后事件全部被捕获。这只是发布观察窗口内的结果，并不保证所有拦截器或网络始终会交付每个事件。

无声的工具链不匹配需要单独修复

Next.js 15 把浏览器设置移入 instrumentation-client.ts。项目启用 Turbopack 后仍停留在 Sentry v9，源映射上传随即停止，却没有明显的应用故障。升级到 Sentry v10 后，兼容的上传路径恢复。

应用还在浏览器、服务器和边缘运行时中初始化 Sentry，并添加路由级及全局错误边界。符号还原属于构建问题；捕获 React、请求和运行时故障则是独立的应用问题。

可读不代表一定有用

beforeSend 钩子添加页面路径、浏览器信息、视口和应用版本标签。它对 API、超时和网络故障进行分类，并在摄取前过滤已知的 Twilio 呼叫限制。

在生产环境中，Session Replay 对正常会话采样 5%，并记录每个错误会话。跟踪最初在预发布环境中以 100% 运行，在生产环境中以 10% 运行；由于消耗过多配额，之后被禁用。采样是一项运维设置，不应盲目照搬。

  • 在构建期间上传私有源映射。
  • 通过同源隧道发送浏览器事件。
  • 区分预期的产品限制和应用故障。
  • 附加路由和回放上下文，让可读的行号同时具备用户流程上下文。