sentry

Sentry

将此技能用于使用 Sentry 进行 TypeScript/JavaScript 应用监控：错误跟踪、追踪、Session Replay、性能分析、日志、指标、source map/版本发布和框架 SDK。快照版本为 JS SDK 11.2.0（2026-10-01；v11 是于 2026-09-23 发布的破坏性主版本——v10 维护线为 10.75.x）。

工作流

1. 更改代码前，先检查本地情况：
   • 已安装的 @sentry/* 版本（让应用 SDK 保持在同一版本线；独立的打包工具插件 / CLI / 向导 / RN / Electron / Capacitor 属于不同版本线）。对于 10.x，先确定任务是否包含升级到 v11，再修改配置。
   • 初始化入口：instrument.ts、sentry.*.config.ts、instrumentation.ts，或最早导入的应用模块。
   • 环境变量：SENTRY_DSN / 公共 DSN、SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT、release、environment。
   • 正在使用的功能：错误、tracesSampleRate / tracesSampler、回放、性能分析、日志、指标、反馈、crons、beforeSend* 钩子、ignoreTransactions / ignoreSpans。
   • 运行时：浏览器、Node（v11 需要 >=20.19）、Bun、Deno、Cloudflare Workers/Pages、AWS/GCP 无服务器、Electron、React Native。
2. 选择与框架匹配的一个最高层级包——不要叠加使用 @sentry/browser + @sentry/react + @sentry/nextjs。参见 packages-frameworks.md。
3. 对于日常设置（初始化顺序、采样、PII、API），请遵循 setup-core.md。
4. 版本有变动时，更新文档。从 source-map.md 开始。
5. 按需查看更深入的细节：
   • 包与框架矩阵：packages-frameworks.md
   • 浏览器/Node 集成与自动插桩：integrations.md
   • 产品功能（回放、日志、性能分析、Seer、Agent）：products-features.md
   • Source map、版本发布、打包工具插件、CLI：sourcemaps-releases.md
   • 模式、陷阱、验证：patterns-troubleshooting.md
   • v10 → v11 升级（默认值、移除的选项、框架迁移）：migration-v10-to-v11.md
6. 命令示例优先使用 bun / bunx。全新框架项目优先使用向导；如果仓库已有自定义工具链，则改用手动初始化。

Sentry 判断

• 先初始化：在导入其他应用模块前加载 instrument / Sentry 配置，以便附加埋点（v11 中基于 channel）和默认集成。
• 每个运行时界面使用一个 SDK 包（客户端与服务端可能不同：例如，Next.js 两端都使用 @sentry/nextjs；TanStack Start 可能使用 @sentry/tanstackstart-react + Cloudflare 封装）。
• 采样：仅在验证安装时使用 tracesSampleRate: 1.0；在生产环境中调低该值，或使用 tracesSampler。回放（replaysSessionSampleRate / replaysOnErrorSampleRate）和性能分析也同样如此。
• PII：v11 移除了 sendDefaultPii；现在如果不设置 dataCollection，就会收集用户信息、Cookie、标头、请求正文、数据库查询数据和 GenAI 输入/输出。对隐私敏感的应用应明确设置 dataCollection 拒绝收集。显式调用 setUser / 设置标签始终会发送数据。
• v11 默认行为：Span 流式传输（beforeSendTransaction / ignoreTransactions 不再生效 → 使用 beforeSendSpan + ignoreSpans）；日志/指标无需标志（已移除 enableLogs）；attachStacktrace: true；Scope 标签不会传递到 Span（使用 setAttribute）。
• 源映射：生产构建需要上传源映射（使用 @sentry/vite-plugin / webpack / esbuild / rollup、框架的 withSentryConfig，或 @sentry/cli）。向客户端提供源映射时，上传后删除公开的 .map 文件。
• 共享环境（扩展、组件、嵌入式库）：不要调用全局 Sentry.init()——使用隔离的 BrowserClient + Scope。
• Node 预加载：v11 对 ESM 和 CJS 都使用 node --import ./instrument.(m)js app.js；--require 和 @sentry/node/preload|init|loader 入口已移除。
• 框架服务端：v11 会自动捕获 Express/Fastify/Koa/Hapi 错误（setup*ErrorHandler 已弃用；通过集成中的 shouldHandleError 调整行为）。Nest 仍使用 SentryModule；Hono 使用 @sentry/hono/<runtime>。
• OpenTelemetry：v11 服务端 SDK 不再拥有 OTel 提供程序；使用 enableOpenTelemetrySetup: true 来接收库的 OTel Span，或在自己的 OTel 管道旁使用 openTelemetryIntegration()。
• 将同一应用中关联的 @sentry/* 包版本统一为相同的 11.x 版本。不要将独立插件（5.x）固定为与 SDK 相同的版本。Electron / RN / Capacitor 仍内嵌 10.x。

验证

优先使用仓库自带的命令。覆盖相关子集：

• bun pm ls @sentry/node（或框架包）——确认版本一致。
• 通过按钮触发测试 captureException / 抛出异常；在 Sentry 中确认 Issue 和源映射后的堆栈。
• 启用追踪后：访问一个 API/页面，并确认 Span 树（v11 中为流式传输的片段）。
• 升级到 v11 后：搜索 sendDefaultPii、enableLogs、enableMetrics、beforeSendTransaction、ignoreTransactions、skipOpenTelemetrySetup、--require、inboundFiltersIntegration、@sentry/types、@sentry/node-core，以及从 @sentry/nextjs 导入的 withSentryConfig。
• 启用回放后：确认 Issue 中关联了 Replay（采样率可能导致延迟）。
• 生产构建：确认源映射上传成功（检查 CI 日志 / Sentry Releases 资源）。
• SENTRY_AUTH_TOKEN 仅在 CI 中存在；DSN 可公开用于客户端，认证令牌不可公开。

报告运行了哪些检查、未运行哪些检查，以及仍有哪些版本假设。