异常、日志与上下文
把错误发进 Sentry 只是第一步。真正能缩短排查时间的是:自动捕获没有被业务代码处理的异常,并在事件上附带用户、页面、操作和网络上下文。
默认会捕获什么
Sentry.init() 会按宿主实际提供的能力注册监听,不需要在每个 onError 中重复调用 captureException。
| 信号 | 默认行为 | 缺少宿主 API 时 |
|---|---|---|
| 未处理 JavaScript 异常 | 监听平台 onError | 跳过,可继续手动捕获 |
| 未处理 Promise rejection | 监听 onUnhandledRejection | 跳过对应监听 |
| 页面不存在 | 监听 onPageNotFound | 跳过对应监听 |
| 内存告警 | 监听 onMemoryWarning | 跳过对应监听 |
| 定时器回调异常 | 默认 TryCatch 集成包裹 | 不影响其它捕获能力 |
初始化必须尽可能早。原生小程序应在入口文件顶部、App() 之前执行;小游戏应放在游戏入口最前面。
Promise 的拒绝原因是 Error 时,SDK 保留其业务堆栈。字符串、数字、Symbol 等原始值没有来源堆栈,会显示为 UnhandledRejection 并记录该值;SDK 不把全局监听器的堆栈当成拒绝来源。业务希望定位拒绝位置时,应使用 Promise.reject(new Error('说明')) 或抛出 Error。beforeSend 的 hint.originalException 保留原始拒绝原因。
平台 onError 提供 Error 时,SDK 保留原异常及其 cause 链。若平台只提供文本或结构化报告,SDK 从可用消息和堆栈提取信息;缺少来源堆栈时不会生成业务位置,定位仍需业务侧保留 Error。
Taro / uni-app 的组件错误可能先被 React 或 Vue 接住,不再冒泡到宿主全局监听。请分别按照 Taro 错误边界或 uni-app errorHandler 接入。
主动上报已处理的问题
当业务代码已经捕获异常,但仍希望记录到 Sentry 时,主动调用上报 API:
try {
await submitOrder();
} catch (error) {
Sentry.captureException(error);
showRetryMessage();
}
Sentry.captureMessage('库存接口连续降级', 'warning');不要在平台全局 onError 中再次上报同一个错误,否则可能与 SDK 自动捕获产生重复事件。
给事件补充排查上下文
SDK 会自动补充设备、系统、应用和小程序宿主 context:
- 顶层
event.platform是 Sentry 标准值javascript;真实宿主在contexts.miniapp.platform。 contexts.app.app_version来自getAccountInfoSync().miniProgram.version,app_identifier来自 AppID。contexts.os.name/version表示操作系统名与系统版本;缺失宿主字段省略,不生成占位值。- SDK 只补充缺失的默认环境字段,保留业务覆盖值。需要关闭自动系统信息采集时,设置
enableSystemInfo: false。 - 宿主客户端 / 基础库版本在
contexts.miniapp.host_version和host_sdk_version,不会冒充小程序发布版本。 onPageNotFound/onMemoryWarning附加的 tag 和 context 只属于当次事件,不会污染后续错误。
用户、标签与业务数据
Sentry.setUser({ id: 'user_123' });
Sentry.setTag('miniapp.channel', 'wechat-search');
Sentry.setContext('order', {
orderId: 'order_456',
paymentMethod: 'balance',
});setUser:关联当前用户,退出登录后可用Sentry.setUser(null)清除。setTag/setTags:适合可筛选、可聚合的短值。setContext/setExtra:适合辅助理解问题的结构化数据。
不要写入密码、访问令牌、完整身份证号等敏感信息。beforeSend 只处理错误与消息事件;独立日志、span 和 metrics 分别使用 beforeSendLog、beforeSendSpan 和 beforeSendMetric。用户反馈应在调用 captureFeedback 前过滤输入。
面包屑
SDK 默认记录页面生命周期、点击 / 触摸和网络请求摘要。
页面生命周期的采集不要求业务先定义 onLoad、onShow、onHide、onReady 或 onUnload;默认页面集成会补齐用于记录的处理器,业务已有处理器仍照常执行。
业务关键动作可以手动补充:
Sentry.addBreadcrumb({
category: 'checkout',
message: '用户确认支付',
level: 'info',
data: { orderId: 'order_456' },
});addBreadcrumb 不会单独发送网络请求。它只会随下一次异常或消息事件一起发送,因此不能用它验证接入是否成功。
SDK 不自动读取交互 dataset;需要关联业务动作时,显式提取允许的字段:
function recordCheckoutAction(event) {
const action = event.currentTarget?.dataset?.action;
if (action === 'confirm' || action === 'cancel') {
Sentry.addBreadcrumb({ category: 'checkout.action', data: { action } });
}
}网络面包屑默认包含 URL、方法、状态码和耗时,不记录请求体与响应体。url 只到路径,query 单列在 url.query 并按 dataCollection.urlQueryParams 过滤。确实需要正文时再开启 traceNetworkBody,先按敏感键过滤、再按 maxRequestBodySize 截断;request_body_size / response_body_size 表示过滤、截断前的可观察字节数,不一定等于网络实际传输量。
URL query、页面与启动入参,以及 JSON/form 正文使用相同的敏感键过滤策略,命中的值替换为 [Filtered]。通过 sensitiveKeys 追加业务键名片段;dataCollection.urlQueryParams: false 关闭 query,正文另由 traceNetworkBody 和 httpBodies 控制。格式限制与过滤范围见配置参考。
独立业务日志
需要独立检索、聚合或告警时,显式调用 logger:
Sentry.init({
dsn: 'YOUR_DSN',
});
Sentry.logger.info('checkout completed', {
orderId: 'order_456',
durationMs: 380,
});| 方式 | 是否独立发送 | 适合用途 |
|---|---|---|
Sentry.logger.* | 是 | 业务日志查询、聚合、告警 |
console.* + enableConsoleBreadcrumbs | 否 | 随错误还原附近的控制台输出 |
addBreadcrumb | 否 | 描述用户操作与业务步骤 |
可用级别为 trace、debug、info、warn、error、fatal。用 beforeSendLog 修改或丢弃不应发送的日志。
收集用户反馈
小程序逻辑层无法直接操作渲染层 DOM,不能使用浏览器 HTML 反馈弹窗。请用原生组件实现表单,再提交数据:
const eventId = Sentry.lastEventId();
Sentry.captureFeedback({
message: '点击支付后页面一直加载',
name: '用户昵称',
associatedEventId: eventId,
tags: { page: 'checkout' },
});反馈输入由业务表单管理;提交前过滤敏感信息。
控制噪声与敏感数据
优先使用声明式过滤;需要按业务逻辑处理时再使用钩子:
Sentry.init({
dsn: 'YOUR_DSN',
ignoreErrors: [/request:fail abort/i],
denyUrls: [/vendor\/unstable-plugin/],
beforeSend(event) {
if (event.user) delete event.user.email;
return event;
},
});完整过滤项与钩子签名见配置项参考 · 过滤与钩子。
验证清单
- 主动调用一次
captureException,确认 Sentry Issues 中出现事件。 - 检查事件是否包含 release、environment、用户、标签和预期面包屑。
- 在框架组件内主动抛错,确认 React Error Boundary 或 Vue errorHandler 生效。
- 发送一条
logger.info,到 Sentry Logs 单独确认。 - 真机与开发者工具都验证一次;宿主监听和网络行为可能不同。
