observability-and-instrumentation

技能简介

本技能指导如何为代码添加仪表化（instrumentation），通过日志、指标、追踪和告警，让生产环境行为可见、可诊断。它解决"功能上线后无法判断系统在做什么、为什么出问题"的困境，强调可观测性应随功能一起编写，而非事后补加。

使用场景

• 开发将运行在生产环境的新功能（新服务、端点、后台任务或外部集成）
• 添加日志、指标、追踪或告警时
• 生产问题被上报，但现有数据无法判断发生了什么
• 设置或审查告警规则
• 审查涉及 I/O、重试、队列或跨服务调用的 PR

使用方法

该技能以 SKILL.md 形式定义，放入 Agent 的 skills 目录后即可自动加载。当任务符合技能描述（如添加可观测性或排查生产问题）时，Agent 会自动按以下流程执行：

1. 先定义"正常工作"：写下值班工程师会问的 2–4 个问题，让每个遥测信号都服务于这些问题；如果连问题都列不出来，说明还没准备好埋点。
2. 选择合适的信号：结构化日志回答"某个具体案例发生了什么"，指标回答"整体多频繁/多快"，追踪回答"时间消耗在哪个服务"。
3. 结构化日志：每条日志应是带稳定事件名和机器可读字段的 JSON 对象；统一使用 error/warn/info/debug 级别；强制携带关联 ID（correlation ID）；严禁记录密钥、Token 和完整 PII。
4. 指标：请求型服务用 RED（Rate、Errors、Duration），资源型用 USE（Utilization、Saturation、Errors）；标签须来自小型固定集合，避免高基数；使用百分位数而非平均值。
5. 分布式追踪：采用 OpenTelemetry 这一厂商中立标准，用自动埋点覆盖 HTTP、gRPC 和常见数据库客户端。

注意事项

• 正在发生的故障诊断请使用 debugging-and-error-recovery 技能；性能剖析优化请使用 performance-optimization 技能；上线日监控清单见 shipping-and-launch 技能。
• 指标标签绝不能使用用户 ID、邮箱、request_id、完整 URL 或错误消息等无界值，这些应放在日志和追踪中。
• 未定义待回答的问题就埋点，最终只会记录大量数据却得不到任何答案。