用途
Sentry 是一个应用监控平台,提供实时错误追踪、性能监控、会话回放和定时任务监控。该技能用于在项目中接入和配置 Sentry,帮助捕获异常并保留完整堆栈,将相似事件归组为 Issue 便于分诊,并通过分布式追踪定位跨服务的性能瓶颈。Sentry 支持 20 多个平台,为 JavaScript、Python、Go、Ruby、Java 等提供专用 SDK。
主要能力
- 错误监控:捕获异常与消息,自动分组为 Issue,管理未解决、已解决、忽略、归档等状态。
- 性能追踪:以 trace、transaction、span 组织请求流程,支持分布式追踪头传播。
- 会话回放:记录 DOM 状态、用户交互、网络请求与控制台日志,默认遮盖全部文本和媒体。
- 定时任务监控与告警:支持 Issue、指标、可用性和 Cron 告警。
- Source Map 上传:通过向导或 CLI 上传,使生产堆栈可读。
- 自定义埋点:设置用户、标签、上下文、面包屑,创建自定义 Span。
使用方式
通过环境变量配置 DSN、Auth Token、组织和项目标识。安装命令包括:
npm install @sentry/browser
npx @sentry/wizard@latest -i nextjs
pip install sentry-sdk
npm install @sentry/node
npm install -g @sentry/cli
初始化时配置 dsn、environment、release、integrations、tracesSampleRate、replaysSessionSampleRate、replaysOnErrorSampleRate 等选项。可用 Sentry.captureException 与 captureMessage 手动上报,用 withScope 隔离上下文,用 startSpan 创建性能 Span。Source Map 可通过 npx @sentry/wizard@latest -i sourcemaps 或 sentry-cli sourcemaps upload --release=my-app@1.0.0 ./dist 上传。
适用场景
适用于新项目或既有项目接入 Sentry、配置错误监控与追踪、集成 Next.js、Django、Flask、Express 等框架、配置发布与 CI/CD、排查采样与 Source Map 相关问题。不适用于与 Sentry 无关的通用日志或单纯 try/catch 最佳实践。
限制与注意事项
Sentry.init 必须是第一个导入,否则相关模块的错误与性能数据不会被捕获。生产环境 tracesSampleRate 设为 1.0 会快速耗尽配额,建议用 tracesSampler 对健康检查和静态资源返回 0。Source Map 必须在该版本首次错误之前上传,否则堆栈永久不可读。会话回放中通过 innerHTML 或 canvas 注入的文本不会被自动遮盖,涉及隐私数据时需先在预发环境审计。Next.js 中 withSentryConfig 的配置合并需使用展开模式,以免静默关闭 webpack 埋点。常见错误包括无效 DSN、429 限流、Source Map 未生效、隧道 CORS 错误和事件不出现,可分别通过核对 DSN、降低采样、重跑向导并提前上传、设置 tunnelRoute、提前初始化解决。