observability-and-instrumentation

可观测性与代码插桩

技能概述

可观测性与代码插桩技能帮助开发者为生产环境代码添加日志、指标、追踪和告警能力，让系统行为从外部可见且可诊断。如果功能上线后没有遥测数据，第一个用户报告的 Bug 就会成为考古挖掘而非简单的查询。

适用场景

生产环境事故诊断：当生产问题报告后，无法从现有数据判断发生了什么，需要通过遥测数据快速定位根本原因。

功能上线监控需求：构建任何将在生产环境运行的功能，包括新服务、接口、后台任务或外部集成时，需要确保系统行为可观测。

告警规则配置审查：设置或审查告警规则时，确保告警基于用户感受到的症状而非系统内部原因，避免告警疲劳。

核心功能

结构化日志与遥测设计：指导开发者编写稳定事件名称和机器可读字段的结构化日志，强制关联 ID 传播，确保每个日志都可查询、可关联。同时帮助选择正确的遥测信号类型——日志回答"具体发生了什么"，指标回答"频率和速度"，追踪回答"时间花在哪里"。

RED/USE 监控指标与基数控制：为请求驱动服务提供 RED 方法（Rate 请求率、Errors 错误率、Duration 延迟直方图），为资源提供 USE 方法（Utilization 利用率、Saturation 饱和度、Errors 错误数）。严格控制标签基数，防止用户 ID、原始 URL、错误消息等无限值域导致监控后端崩溃。

症状告警与 OpenTelemetry 集成：告警必须基于用户感受到的症状（错误率 >1%、p99 延迟 >2s）而非系统原因（CPU 85%、磁盘 70%），每个告警链接到可操作的 Runbook。通过 OpenTelemetry 实现分布式追踪的零代码自动插桩，支持 HTTP、gRPC 和常见数据库客户端，确保跨服务请求追踪完整无断点。

常见问题

什么时候应该为代码添加监控？

在编写功能代码的同时就应该添加监控，而不是在功能"完成"之后。监控是功能的一部分，就像测试一样。如果功能上线时没有遥测数据，第一次生产事故时你将无法判断发生了什么，到时候添加监控的成本远高于开发时一次写好。

生产环境发生事故时如何快速定位问题？

首先确保每个请求都有关联 ID（Correlation ID）贯穿所有日志、追踪和跨服务调用。然后在 Tracing UI 中跟随单个请求的完整路径，查看每个 hop 的耗时。同时查询结构化日志中的事件字段（如 payment_failed、errorCode）和 RED 指标的 p95/p99 延迟，判断是业务逻辑问题、第三方超时还是资源饱和。如果没有这些遥测数据，定位问题只能靠猜测和反复修改尝试。

为什么告警太多会导致团队麻木？

因为告警如果基于系统内部原因（CPU 使用率、内存、重启次数）而非用户症状，会在系统正常运行时频繁触发，而真正的用户故障却被漏掉。告警疲劳让运维人员习惯性地忽略所有告警。正确做法是只对用户可感知的症状（错误率、延迟、队列积压）建立告警，并且每个告警必须可操作——如果默认反应是"忽略它，它会自愈"，那这个告警应该删除。