Become a sponsor
5.17 链路追踪与指标
概述
可观测性由两个轻量机制承担：trace 中间件为每个请求分配 trace_id 并回显响应头，串联全部日志；metrics 中间件按路由模板采集 Prometheus 指标。两者都在链路最前段，保证后续一切事件可观测。
链路追踪（trace，链首）
text
入站 X-Request-Id → 透传为 trace_id（缺失/超长>64 字符则本地随机生成）
↓
回显 X-Request-Id 响应头
↓
ctx 写入：trace_id + 客户端IP + UA + 方法 + URL
↓
后续全部日志（zap / 操作日志 / 登录日志）携带同一 trace_idOPTIONS 预检只注入 trace_id、不写请求元信息——防预检风暴产生日志噪音。
排查套路：前端/网关拿到响应的 X-Request-Id → 用它 grep 日志文件 → 一次请求的全链日志秒级定位。
Prometheus 指标（metrics）
| 指标 | 类型 | 标签 |
|---|---|---|
| easygoadmin_http_requests_total | Counter | route（路由模板）、method、status、result |
| easygoadmin_http_request_duration_seconds | Histogram | route、method |
- result 为有限枚举（success/denied/error），拒绝类请求也计入 QPS 与错误率
/metrics自身与/api/health不计量（防递归与噪音）- 端点受
api.metrics开关控制，生产可关闭或由网关/内网保护
高基数红线
trace_id 只进日志，严禁进 Prometheus label。label 仅允许有限枚举：路由模板（非真实路径）、方法、状态、结果。真实路径含 ID 段会把 label 打爆（内存耗尽）。
位置设计
| 中间件 | 位置 | 理由 |
|---|---|---|
| trace | 链首 | 日志/异常/拒绝发生前 trace_id 必须就绪 |
| metrics | CORS 后、Response 前 | panic 恢复与各层拒绝都发生在计时区间内，QPS/错误率完整 |
消费方式
- 排障：X-Request-Id + 日志文件检索
- 监控告警：Prometheus 抓取 /metrics，按 route 维度配错误率/耗时告警
- 容量评估：duration 直方图看长尾