5.17 链路追踪与指标

:::tip 概述可观测性由两个轻量机制承担：trace 中间件为每个请求分配 trace_id 并回显响应头，串联全部日志；metrics 中间件按路由模板采集 Prometheus 指标。两者都在链路最前段，保证后续一切事件可观测。 :::

链路追踪（trace，链首）

入站 X-Request-Id → 透传为 trace_id（缺失/超长>64 字符则本地随机生成）
        ↓
回显 X-Request-Id 响应头
        ↓
ctx 写入：trace_id + 客户端IP + UA + 方法 + URL
        ↓
后续全部日志（zap / 操作日志 / 登录日志）携带同一 trace_id

OPTIONS 预检只注入 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 直方图看长尾

下一步

→ 5.18 服务与缓存监控

2.1 KiB Raw Blame History Unescape Escape