api-observability-axiom-pino-sentry

可观测性模式（日志记录、追踪、错误处理）

快速指南： 使用 Pino 进行结构化日志记录（debug/info/warn/error）。使用关联 ID 追踪请求。在 React 中使用 Sentry 错误边界。完成身份验证后附加用户上下文。过滤预期错误（404）。创建 Axiom 监控项以触发告警。

---

<critical_requirements>

重要：使用此技能前

所有代码必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入排序、import type、命名常量）

（必须在所有日志语句中包含关联 ID，以便追踪请求）

（必须使用包含必需字段的结构化日志：level、message、correlationId、timestamp）

（必须从 Sentry 中过滤预期错误（404、验证错误），避免浪费配额）

（必须在身份验证完成后，将用户上下文附加到 Sentry）

（必须使用带上下文的子日志记录器，而不是在每次日志调用中重复字段）

</critical_requirements>

---

自动检测： log、logger、pino、Sentry、错误边界、关联 ID、trace、span、可观测性、监控、告警

适用场景：

• 为新功能代码添加日志记录
• 实现错误处理模式
• 使用关联 ID 设置请求追踪
• 为性能调试创建自定义 trace 和 span
• 在 React 组件中配置 Sentry 错误边界
• 创建 Axiom 监控项和告警

不适用场景：

• 初始项目设置和依赖安装（一次性设置；请遵循官方文档）
• 特定框架的配置文件（请遵循框架 SDK 文档）

涵盖的关键模式：

• 日志级别决策树（何时使用 debug/info/warn/error）
• 包含必需字段的结构化日志
• 关联 ID：生成、传播、附加到日志
• 使用 OpenTelemetry 创建自定义 trace/span
• React 中的 Sentry 错误边界
• 身份验证后将用户上下文附加到 Sentry
• 创建 Axiom 监控项和告警
• 过滤噪声（404 等预期错误）
• 性能监控模式
• 调试指南：追踪系统中的请求

详细资源：

• 代码示例请参见 examples/core.md（始终加载的基本模式）
• 决策框架和反模式请参见 reference.md

扩展示例：

• examples/correlation-ids.md - 用于请求追踪的中间件
• examples/tracing.md - OpenTelemetry span 和自定义插桩
• examples/error-boundaries.md - 配合 Sentry 使用的 React 错误边界
• examples/sentry-config.md - 用户上下文和错误过滤
• examples/axiom.md - 监控项、告警和调试查询
• examples/performance.md - 查询和 API 调用追踪

---

理念

良好的可观测性能够回答三个问题：

1. 发生了什么？（包含上下文的结构化日志）
2. 为什么会发生？（包含堆栈跟踪的错误追踪）
3. 如何找到它？（关联相关事件的关联 ID）

日志记录应当有目的，而非防御性。每条日志语句都应回答一个你在调试时可能提出的具体问题。避免“以防万一”而记录日志——这会产生噪声，让真正的问题更难发现。

---

核心模式

模式 1：日志级别决策树

根据具体情况选择适当的日志级别。

What are you logging?
├─ Development-only debugging info?
│   └─ debug (filtered in production)
├─ Normal operation events?
│   ├─ Request started/completed → info
│   ├─ User action completed → info
│   └─ Background job finished → info
├─ Something unexpected but recoverable?
│   ├─ Retry attempt → warn
│   ├─ Fallback used → warn
│   └─ Deprecation notice → warn
└─ Something that needs attention?
    ├─ Unhandled exception → error
    ├─ External service failure → error
    └─ Data integrity issue → error

级别指南：

级别	生产环境	使用场景
debug	已过滤	开发调试、详细跟踪
info	可见	正常操作、请求生命周期、用户操作
warn	可见	可恢复的问题、重试、回退
error	可见 + 告警	不可恢复的问题、故障、异常

代码示例请参阅 examples/core.md。

---

模式 2：包含必需字段的结构化日志

每条日志语句都应包含结构化上下文，以便搜索。

必需字段：

字段	类型	用途
correlationId	string	将同一请求的所有日志关联起来
service	string	标识服务（api、web、worker）
operation	string	正在执行的操作
userId	string?	执行操作的用户（如果已通过身份验证）
duration	number?	耗时（毫秒；适用于已完成的操作）

代码示例请参阅 examples/core.md。

---

模式 3：用于请求跟踪的关联 ID

生成并传递关联 ID，以跨服务跟踪请求。

关键组件：

1. 关联 ID 中间件 - 从标头生成／提取关联 ID
2. 请求日志记录器中间件 - 创建带有关联上下文的请求级日志记录器
3. 路由处理程序用法 - 子日志记录器会自动继承关联 ID

现代替代方案：AsyncLocalStorage + Mixin

对于较大型的应用程序，可使用 AsyncLocalStorage 与 Pino 的 mixin 选项自动注入上下文，无需在每个处理程序中手动创建子日志记录器。

两种方法的实现示例请参阅 examples/correlation-ids.md。

---

模式 4：使用 OpenTelemetry 创建自定义跟踪和跨度

添加自定义检测，以便调试性能问题。

关键工具：

• withSpan() - 将异步操作包装在跟踪跨度中
• createSpan() - 为同步操作创建简单跨度

代码示例请参阅 examples/tracing.md。

---

模式 5：React 中的 Sentry 错误边界

捕获并报告 React 组件错误，并支持恢复。

关键组件：

1. ErrorBoundary - 用于捕获渲染错误的类组件
2. global-error.tsx - SSR 框架的全局错误处理程序
3. 功能级边界 - 使用自定义回退 UI 包装功能区块

实现示例请参阅 examples/error-boundaries.md。

---

模式 6：将用户上下文附加到 Sentry

在身份验证成功后向 Sentry 添加用户信息，以便更好地调试。

关键函数：

• setSentryUser() - 在身份验证成功后调用
• clearSentryUser() - 在注销时调用
• setSentryContext() - 为各功能添加额外上下文

代码示例请参阅 examples/sentry-config.md。

---

模式 7：过滤预期错误

避免预期错误占用 Sentry 配额并触发告警。

过滤策略：

1. beforeSend 钩子 - 按错误消息模式过滤
2. HTTP 状态码过滤 - 跳过 404、401、403
3. beforeBreadcrumb 钩子 - 移除嘈杂的 console.log 面包屑

配置示例请参阅 examples/sentry-config.md。

---

模式 8：创建 Axiom 监控和告警

为生产问题设置主动监控。

监控类型：

1. 错误率监控 - 错误率 > 1% 时发出告警
2. 延迟监控 - P95 > 2 秒时发出告警
3. 特定错误监控 - 发生数据库连接错误时发出告警

APL 查询示例请参阅 examples/axiom.md。

---

模式 9：性能监控模式

跟踪并优化运行缓慢的操作。

跟踪工具：

• trackedQuery() - 为数据库查询添加性能跟踪
• trackedApiCall() - 为外部 API 调用添加性能跟踪

实现示例请参阅 examples/performance.md。

---

模式 10：调试指南 - 跟踪请求

调试时如何跟踪请求在系统中的流转。

步骤：

1. 从响应标头、Sentry 或用户报告中获取关联 ID
2. 在 Axiom 中搜索所有包含该关联 ID 的日志
3. 使用时间线视图分析请求流程
4. 查找相关错误和堆栈跟踪
5. 在 Sentry 中查看其他上下文

详细的 APL 查询和检查清单请参阅 examples/axiom.md。

---

<red_flags>

危险信号

全面的反模式和危险信号请参阅 reference.md。

快速参考 - 高优先级问题：

• 日志中缺少关联 ID - 无法跟踪请求
• 使用 console.log 而不是结构化日志记录器 - 无法搜索，也没有级别
• 记录敏感数据 - 安全漏洞
• 未在 Sentry 中过滤预期错误 - 浪费配额，掩盖真正的问题
• 错误日志没有堆栈跟踪 - 不知道错误发生的位置就无法调试

</red_flags>

---

<critical_reminders>

重要提醒

所有代码必须遵循 CLAUDE.md 中的项目约定

（必须在所有日志语句中包含关联 ID，以便跟踪请求）

（必须使用包含必需字段的结构化日志记录：level、message、correlationId、timestamp）

（必须从 Sentry 中过滤预期错误（404、验证错误），以避免浪费配额）

（必须在身份验证完成后将用户上下文附加到 Sentry）

（必须使用带上下文的子日志记录器，而不是在每次日志调用中重复字段）

未能遵循这些规则将导致请求无法跟踪、浪费 Sentry 配额，并使调试变得不可能。

</critical_reminders>