vault backup: 2026-06-03 10:30:42

hzh/Gen2D/07-可观测性.md

@@ -1,28 +1,19 @@
-# 07 — 可观测性
+---
+tags: [observability, prometheus, grafana, metrics, alerting, monitoring]
+create time: 2026-06-03 10:30
+---
 
-> **一句话概括**：35 个 Prometheus 指标 + 3 个 Grafana 仪表盘 + 10 条告警规则，覆盖全栈，让系统运行状态一目了然。
+# 07. 可观测性
+
+## 概述
+
+35 个 Prometheus 指标 + 3 个 Grafana 仪表盘 + 10 条告警规则，覆盖全栈，让系统运行状态一目了然。
 
 ---
 
-```mermaid
-flowchart LR
-    A["🌐 Request"] --> B["📊 Metrics<br/>Middleware"]
-    B --> C["⚙️ Application<br/>Logic"]
-    C --> D["📈 Prometheus<br/>Scrape"]
-    D --> E["📉 Grafana<br/>Dashboard"]
-    D --> F["🚨 AlertManager<br/>Notify"]
+## 正文
 
-    style A fill:#e3f2fd,stroke:#1976d2
-    style B fill:#fff3e0,stroke:#f57c00
-    style C fill:#e8f5e9,stroke:#388e3c
-    style D fill:#fce4ec,stroke:#c62828
-    style E fill:#e8eaf6,stroke:#303f9f
-    style F fill:#ffebee,stroke:#b71c1c
-```
-
----
-
-## 📐 指标体系总览
+## 指标体系总览
 
 Gen2D 遵循 Prometheus 命名最佳实践，所有指标使用 `gen2d_` 前缀，共 **35 个指标**，分为 **6 大组**：
 
@@ -37,9 +28,9 @@ Gen2D 遵循 Prometheus 命名最佳实践，所有指标使用 `gen2d_` 前缀
 
 ---
 
-## 📊 五大指标组详解
+## 五大指标组详解
 
-### 1️⃣ HTTP 层指标
+### HTTP 层指标
 
 Gin 中间件自动采集，**零业务代码侵入**。
 
@@ -51,9 +42,10 @@ Gin 中间件自动采集，**零业务代码侵入**。
 | `gen2d_http_response_size_bytes` | Histogram | method, path | 响应体大小 |
 | `gen2d_http_requests_in_flight` | Gauge | — | 当前并发请求数 |
 
-> 💡 **FullPath() 的关键作用**：使用路由模板 `/api/v1/tasks/:taskId` 而非实际路径 `/api/v1/tasks/abc123`，避免高基数标签导致 Prometheus 内存爆炸。
+> [!tip] FullPath() 的关键作用
+> 使用路由模板 `/api/v1/tasks/:taskId` 而非实际路径 `/api/v1/tasks/abc123`，避免高基数标签导致 Prometheus 内存爆炸。
 
-### 2️⃣ 限流层指标
+### 限流层指标
 
 | 指标名 | 类型 | 标签 | 说明 |
 |--------|------|------|------|
@@ -63,7 +55,7 @@ Gin 中间件自动采集，**零业务代码侵入**。
 - `scope`：`user` / `global`
 - `result`：`allowed` / `denied`
 
-### 3️⃣ 任务队列层指标
+### 任务队列层指标
 
 | 指标名 | 类型 | 标签 | 说明 |
 |--------|------|------|------|
@@ -75,7 +67,7 @@ Gin 中间件自动采集，**零业务代码侵入**。
 
 - `driver`：`memory` / `rabbitmq`
 
-### 4️⃣ 协程池层指标
+### 协程池层指标
 
 | 指标名 | 类型 | 标签 | 说明 |
 |--------|------|------|------|
@@ -86,7 +78,7 @@ Gin 中间件自动采集，**零业务代码侵入**。
 | `gen2d_pool_rejected_total` | Counter | — | 被拒绝的任务 |
 | `gen2d_pool_task_duration_seconds` | Histogram | — | 任务执行耗时 |
 
-### 5️⃣ Pipeline 业务层指标
+### Pipeline 业务层指标
 
 | 指标名 | 类型 | 标签 | 说明 |
 |--------|------|------|------|
@@ -96,9 +88,10 @@ Gin 中间件自动采集，**零业务代码侵入**。
 | `gen2d_pipeline_retries_total` | CounterVec | stage | 各阶段重试次数 |
 | `gen2d_pipeline_tasks_active` | Gauge | — | 当前执行中的 Pipeline 数 |
 
-> 🔍 **stage_duration 定位瓶颈**：通过 `stage` 标签（如 `asset_generator`、`quality_check`）可以精确定位哪个阶段是性能瓶颈。
+> [!tip] stage_duration 定位瓶颈
+> 通过 `stage` 标签（如 `asset_generator`、`quality_check`）可以精确定位哪个阶段是性能瓶颈。
 
-### 6️⃣ 基础设施层指标
+### 基础设施层指标
 
 | 指标名 | 类型 | 标签 | 说明 |
 |--------|------|------|------|
@@ -110,7 +103,7 @@ Gin 中间件自动采集，**零业务代码侵入**。
 
 ---
 
-## 🔧 中间件集成
+## 中间件集成
 
 ### Metrics 中间件工作流程
 
@@ -136,7 +129,7 @@ func Metrics() gin.HandlerFunc {
 
 ---
 
-## 📉 Grafana 仪表盘
+## Grafana 仪表盘
 
 | 仪表盘 | 用途 | 关键面板 |
 |--------|------|---------|
@@ -146,7 +139,7 @@ func Metrics() gin.HandlerFunc {
 
 ---
 
-## 🚨 告警规则
+## 告警规则
 
 共 **10 条告警规则**，覆盖限流、队列、协程池、管线和基础设施：
 
@@ -163,11 +156,12 @@ func Metrics() gin.HandlerFunc {
 | `HighErrorRate` | 🔴 | 5xx 错误率 > 5%（持续 5m） | 服务异常 |
 | `HighLatency` | ⚠️ | P95 延迟 > 5s（持续 5m） | 影响用户体验 |
 
-> 🛡️ **告警级别说明**：🔴 Critical 表示需要立即处理，⚠️ Warning 表示需要关注但不紧急。
+> [!note] 告警级别说明
+> Critical 表示需要立即处理，Warning 表示需要关注但不紧急。
 
 ---
 
-## 📦 基础设施指标
+## 基础设施指标
 
 除业务指标外，Gen2D 还监控外部依赖的健康状态：
 
@@ -194,9 +188,8 @@ flowchart LR
 
 ---
 
-## 🔗 关联文档
+## 关联文档
 
-- [← 返回索引](00-index.md)
-- [10 — 中间件链](10-middleware-chain.md) — Metrics 中间件的挂载位置
-- [09 — 限流](09-rate-limiting.md) — 限流指标的采集方式
-- [14 — 部署架构](14-deployment.md) — Prometheus + Grafana 的部署配置
+- [[10-中间件链]] — Metrics 中间件的挂载位置
+- [[09-限流]] — 限流指标的采集方式
+- [[14-部署架构]] — Prometheus + Grafana 的部署配置