sentry-integration

Sentry 集成

按照固定的操作顺序和明确的决策规则实现 Sentry 集成。将项目特定的细节放在参考文件中，以保持此技能可跨 Agent 使用。

触发条件

当请求涉及以下任一内容时，加载此技能：

• Sentry SDK 配置或迁移
• 错误追踪、异常捕获或预期错误分类
• 埋点和 Span 设计
• 性能问题、请求缓慢、Trace 分析或采样策略
• TRPC、HTTP 处理程序或服务端函数的中间件接入
• 用于 Issue、项目或告警的 Sentry API

操作工作流（必须按顺序执行）

1. 配置 SDK（先服务端，后客户端）。
2. 在框架边界接入中间件。
3. 在捕获和 beforeSend 之前对预期错误进行分类。
4. 仅在默认集成不足时添加追踪。
5. 首先在非生产环境中验证事件、Span、标签和噪声过滤。

按此顺序执行步骤，避免产生噪声遥测数据和 Trace 上下文损坏。

1) 配置 SDK

明确设置环境、发布版本和采样。确保健康检查和合成流量不会进入 Trace。

使用 references/sentry-code-samples.md 中的服务端和客户端初始化示例。

2) 接入中间件

在共享边界接入 Sentry 中间件，而不只是接入某个过程导出项。

将相同的中间件规则应用于所有过程链：

• publicProcedure
• 已认证／受保护的过程
• 管理员或按组织范围限定的过程
• 自定义组合链

使用 references/sentry-code-samples.md 中的 TRPC 和服务端函数示例。

3) 分类预期错误

将预期的业务错误标记为已处理，以减少告警噪声，同时保留可观测性。

在以下两个位置对预期错误进行分类：

• 自定义 captureException 封装器
• SDK beforeSend

在 beforeSend 中，始终从 hint.originalException（或等效辅助函数）读取可抛出对象。不要引用未定义的 error 变量。

使用 references/sentry-code-samples.md 中固定的 beforeSend 示例和辅助函数。

4) 添加追踪

优先使用内置集成，仅对未覆盖的路径添加手动追踪。

数据库追踪决策规则

• 使用受支持的 PostgreSQL 驱动程序和标准查询路径时，使用 postgresIntegration。
• 查询绕过受支持的集成、需要封装 Drizzle／自定义构造器，或需要操作级命名时，使用手动／代理追踪。
• 避免在同一查询路径上同时运行两种策略，以免产生重复 Span。

使用 references/sentry-code-samples.md 中的手动追踪和代理追踪示例。

5) 验证

通过简短的检查清单验证每项集成变更：

1. 触发一个预期错误，确认事件以警告级别记录并标记为已处理。
2. 触发一个意外错误，确认其进入错误级别的告警路径。
3. 执行一个已埋点的请求，确认 Trace 连续性。
4. 确认健康检查路由已排除。
5. 确认没有重复的数据库 Span。

Sentry API 服务范围

将 Sentry API 服务工作（Issue／项目／令牌验证）视为可选的高级模块。仅当实现仍处于 Sentry 集成范围内时，才将其保留在同一技能中；否则应拆分为专门的操作技能。

使用 references/sentry-code-samples.md 中面向 Effect 的 API 服务示例。

核心规则

1. 遵循工作流顺序：配置 SDK → 接入中间件 → 分类预期错误 → 添加追踪 → 验证。
2. 保留预期错误的可观测性，同时将其标记为已处理。
3. 确保所有过程链的中间件覆盖保持一致。
4. 优先使用内置数据库集成，再考虑手动／代理追踪。
5. 在发布前于非生产环境中验证集成行为。
6. 将大型代码示例保存在参考文件中；将决策规则保留在 SKILL.md 中。