错误追踪集成器
将错误追踪服务集成到应用程序中,以便更好地进行生产环境调试和监控。
使用时机
- 用户要求进行错误监控或追踪
- 设置生产环境错误日志
- 用户提到“Sentry”、“错误追踪”、“崩溃报告”或“生产环境调试”\n
操作指南
1. 检测框架
识别应用框架:
- React、Vue、Angular(前端)
- Express、Fastify(Node.js 后端)
- Django、Flask(Python)
- Rails(Ruby)
2. 选择错误追踪服务
热门服务:
- Sentry:最流行、功能全面
- Rollbar:适用于后端
- Bugsnag:跨平台
- Airbrake:侧重于 Ruby
- LogRocket:会话回放 + 错误
3. 安装与配置
Sentry(React 示例):
npm install @sentry/react
import * as Sentry from "@sentry/react";
Sentry.init({
dsn: process.env.REACT_APP_SENTRY_DSN,
environment: process.env.NODE_ENV,
tracesSampleRate: 1.0,
integrations: [
new Sentry.BrowserTracing(),
new Sentry.Replay()
],
});
Sentry(Node.js/Express):
const Sentry = require("@sentry/node");
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.NODE_ENV,
tracesSampleRate: 1.0,
});
// 请求处理中间件(放置于第一个中间件)
app.use(Sentry.Handlers.requestHandler());
// 错误处理中间件(放在所有路由之后,错误中间件之前)
app.use(Sentry.Handlers.errorHandler());
4. 添加错误边界(React)
import { ErrorBoundary } from '@sentry/react';
function App() {
return (
<ErrorBoundary fallback={<ErrorFallback />}>
<YourApp />
</ErrorBoundary>
);
}
5. 添加上下文
用户上下文:
Sentry.setUser({
id: user.id,
email: user.email,
username: user.username
});
标签:
Sentry.setTag("page_locale", "en-US");
Sentry.setTag("feature_flag", "new_ui");
上下文:
Sentry.setContext("order", {
id: order.id,
total: order.total,
items: order.items.length
});
6. 面包屑
追踪导致错误的用户操作:
Sentry.addBreadcrumb({
category: "auth",
message: "用户已登录",
level: "info"
});
Sentry.addBreadcrumb({
category: "ui",
message: "按钮已点击",
data: { buttonId: "submit-form" }
});
7. 手动捕获错误
try {
riskyOperation();
} catch (error) {
Sentry.captureException(error, {
tags: { section: "payment" },
level: "error",
extra: { orderId: order.id }
});
}
8. 过滤敏感数据
擦除 PII(个人身份信息):
Sentry.init({
beforeSend(event, hint) {
// 不发送包含敏感数据的内容
if (event.request?.data?.password) {
delete event.request.data.password;
}
return event;
},
ignoreErrors: [
// 忽略浏览器扩展错误
/extensions\//i,
/^Non-Error promise rejection/,
]
});
9. 源映射(生产环境)
启用源映射以获取可读的堆栈跟踪:
Webpack:
// webpack.config.js
module.exports = {
devtool: 'source-map',
plugins: [
new SentryWebpackPlugin({
org: "your-org",
project: "your-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
include: "./dist",
}),
],
};
10. 告警配置
为以下内容设置告警:
- 新问题
- 问题回归(已解决的问题再次出现)
- 错误率飙升
- 关键错误(支付、认证失败等)
11. 性能监控
添加事务追踪:
const transaction = Sentry.startTransaction({
name: "processOrder",
op: "task"
});
try {
await processOrder();
} finally {
transaction.finish();
}
12. 最佳实践
- 环境分离:为开发/预发布/生产环境使用不同的项目
- 版本追踪:使用发布版本标记错误
- 采样率:错误100%上报,性能降低采样
- 团队通知:集成 Slack/邮件通知
- 问题分配:自动分配给代码负责人
- 错误分组:使用自定义指纹实现更好的分组
- 不要记录敏感数据:PII、密码、令牌
支持文件
templates/sentry-react.js:React 集成模板templates/sentry-node.js:Node.js 集成模板templates/sentry-python.py:Python 集成模板