签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -0,0 +1,53 @@
+# 5.17 链路追踪与指标
+
+:::tip 概述
+可观测性由两个轻量机制承担：**trace 中间件**为每个请求分配 trace_id 并回显响应头，串联全部日志；**metrics 中间件**按路由模板采集 Prometheus 指标。两者都在链路最前段，保证后续一切事件可观测。
+:::
+
+## 链路追踪（trace，链首）
+
+```text
+入站 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 服务与缓存监控](/zh/core/server-monitor.html)