API 可观测性是什么
面向接口的可观测性围绕四类信号：流量（请求量与并发）、错误（错误率与错误分类）、延迟（P50/P95/P99 与超时占比）、饱和度（连接池、线程池与队列水位）。这些信号必须能按接口、调用方与状态码维度切片，否则「系统变慢了」只能靠猜。结构化日志与分布式追踪把三者串起来：用 trace ID 从一次慢请求下钻到具体服务与依赖，才是可观测而不是仅仅有监控数据。
基本信息
| 四类信号 | 流量、错误、延迟分位、饱和度 |
|---|---|
| 切片维度 | 接口路径、调用方、状态码、版本、地域 |
| 日志要求 | 结构化输出，字段含关联 ID、耗时与上下游标识 |
| 追踪要求 | 上下文跨服务传播，采样率按流量与预算调整 |
| 告警原则 | 绑定用户可感知症状（错误率、延迟超标），而非只看资源指标 |
典型使用场景
- 发布验证：新版本上线后按接口维度对比错误率与延迟分位
- 故障定位：从告警下钻到追踪，再落到具体日志明细
- 容量规划：按接口与调用方统计请求量增长趋势
- 消费者管理：识别异常高频调用方并做限流或沟通
- SLO 计算：用成功率与延迟分位支撑错误预算与发布节奏
- 依赖分析：按下游维度统计耗时占比，找出放大故障的链路
结构化日志要素
结构化日志要素
{
"ts": "2026-10-13T10:00:00Z",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", // 跨服务联查的关联标识
"api": "/v1/orders", // 接口维度，告警按此聚合
"consumer": "app-a", // 调用方维度，定位异常消费者
"status": 200, // 状态码，区分 4xx 与 5xx
"dur_ms": 23, // 单次耗时，用于分位统计
"upstream": "gateway-3", // 上下游标识，便于链路还原
"error_code": null // 业务错误码，按类型分支
}信号与解读
| 信号 | 关注指标 | 异常时的表现 |
|---|---|---|
| 流量 | QPS、并发请求数、按调用方拆分 | 单调用方突增，占比异常 |
| 错误 | 错误率与 4xx、5xx 分类 | 5xx 上升说明服务端问题；4xx 上升多为接入方变更 |
| 延迟 | P50/P95/P99 与超时占比 | P99 陡升而均值平稳，通常是排队或慢依赖 |
| 饱和度 | 连接池占用、线程池排队、队列水位 | 水位持续高位说明容量或下游限速 |
不要只看平均延迟：长尾问题会被均值掩盖，P99 用户持续受影响而监控显示一切正常，容量与体验问题被拖延。
日志必须结构化：无法按接口、调用方与状态码聚合的日志，在排障时只能逐台检索，故障窗口内的定位时间主要浪费在这上面。