@umacloud/knowledge 1.0.1

package/observability/02-playbooks/prometheus-grafana-playbook.md

@@ -0,0 +1,135 @@
+---
+id: prometheus-grafana-playbook
+title: Prometheus + Grafana 监控告警实战手册
+domain: observability
+category: 02-playbooks
+difficulty: advanced
+tags: [prometheus, grafana, monitoring, alerting, slo, red, use, golden-signals, alertmanager, dashboard, metrics, enterprise]
+quality_score: 95
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# Prometheus + Grafana 监控告警实战手册
+
+> 基于 [Grafana Alerting Best Practices](https://grafana.com/docs/grafana/latest/alerting/guides/best-practices/) + [Grafana Dashboard Best Practices](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/best-practices/)
+
+## 四大黄金信号
+
+### 服务的 RED 指标（每个端点必须）
+```
+Rate     — 每秒请求数（QPS）
+Errors   — 错误率（5xx / 总请求）
+Duration — 延迟分布（p50/p95/p99）
+```
+
+### 基础设施的 USE 指标
+```
+Utilization — 使用率（CPU/内存/磁盘）
+Saturation  — 饱和度（队列长度/连接池）
+Errors      — 错误（丢包/重传/失败）
+```
+
+## Prometheus 指标暴露
+
+```python
+# Python 应用暴露 /metrics
+from prometheus_client import Counter, Histogram, generate_latest
+
+REQUESTS = Counter('http_requests_total', 'Total requests', ['method', 'path', 'status'])
+LATENCY = Histogram('http_request_duration_seconds', 'Request latency',
+    ['path'],
+    buckets=[0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]  # 自定义桶
+)
+
+@app.get("/metrics")
+def metrics():
+    return generate_latest()
+
+@app.middleware("http")
+async def track_metrics(request, call_next):
+    start = time.time()
+    response = await call_next(request)
+    duration = time.time() - start
+    REQUESTS.labels(method=request.method, path=request.url.path, status=response.status_code).inc()
+    LATENCY.labels(path=request.url.path).observe(duration)
+    return response
+```
+
+## SLO + 错误预算告警
+
+```yaml
+# ❌ 静态阈值（不知道是正常波动还是真的故障）
+alert: HighErrorRate
+expr: rate(http_requests_total{status=~"5.."}[1m]) > 0.01
+
+# ✅ 基于错误预算的 SLO 告警（Google SRE 方法）
+# SLO: 99.9% 的请求在 30 天内成功
+# 错误预算: 0.1% × 30天 = 43.2 分钟的允许故障时间
+
+# 快速燃烧（1小时耗 2% 预算 → P1）
+alert: SLOBurnRateFast
+expr: |
+  (
+    sum(rate(http_requests_total{status=~"5.."}[5m]))
+    / sum(rate(http_requests_total[5m]))
+  ) > (14.4 * 0.001)  # 14.4x 标准燃烧率
+for: 2m
+
+# 慢速燃烧（6小时耗 5% 预算 → P2）
+alert: SLOBurnRateSlow
+expr: |
+  (
+    sum(rate(http_requests_total{status=~"5.."}[1h]))
+    / sum(rate(http_requests_total[1h]))
+  ) > (3 * 0.001)  # 3x 标准燃烧率
+for: 15m
+```
+
+## 告警原则（防 Alert Fatigue）
+
+1. **告症状不告原因** — "用户下单失败率高" > "CPU 80%"
+2. **每个告警有 runbook** — 告警描述里含处理链接
+3. **按优先级分级** — P1（PagerDuty）/ P2（Slack）/ P3（邮件）
+4. **用 `for` 持续时间过滤抖动** — 持续 5 分钟才告警
+5. **抑制规则** — 父告警触发时抑制子告警（DB 挂 → 抑制所有 API 告警）
+
+```yaml
+# Alertmanager 抑制规则
+inhibit_rules:
+- source_match: { severity: critical }
+  target_match: { severity: warning }
+  equal: ['service']  # 同服务的 critical 抑制 warning
+```
+
+## Grafana 仪表盘设计
+
+### 黄金仪表盘布局
+```
+┌─────────────────────────────────────────┐
+│ Row 1: 概览（错误率 + p95 延迟 + QPS）    │
+├─────────────────────────────────────────┤
+│ Row 2: 错误细节（按端点/状态码分组）       │
+├─────────────────────────────────────────┤
+│ Row 3: 延迟分布（p50/p95/p99 曲线）       │
+├─────────────────────────────────────────┤
+│ Row 4: 资源使用（CPU/内存/连接池）        │
+├─────────────────────────────────────────┤
+│ Row 5: 业务指标（订单量/收入/活跃用户）    │
+└─────────────────────────────────────────┘
+```
+
+### 阈值标注
+- 绿色：< SLO 目标
+- 黄色：接近 SLO 边界
+- 红色：超过 SLO（需关注）
+
+## 生产检查清单
+- [ ] 每个端点暴露 RED 指标
+- [ ] 每个资源暴露 USE 指标
+- [ ] SLO 定义 + 错误预算告警
+- [ ] 告警有 runbook + 优先级分级
+- [ ] 抑制规则（防告警风暴）
+- [ ] Grafana 仪表盘（概览 + 细节 + 业务）
+- [ ] 告警静默窗口（维护期不告警）
+- [ ] 指标保留 15 天（长期用 Thanos/Mimir）

package/observability/02-playbooks/structured-logging-playbook.md

@@ -0,0 +1,73 @@
+---
+id: structured-logging-playbook
+title: 结构化日志实战手册
+domain: observability
+category: 02-playbooks
+difficulty: intermediate
+tags: [observability, logging, structured-logging, request-id, correlation, json, tracing, elk, loki]
+quality_score: 90
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 结构化日志实战手册
+
+## 为什么用结构化日志
+
+```
+# ❌ 非结构化（无法搜索/聚合/告警）
+[2024-06-14 10:30:00] INFO User 123 created order 456 for $99.50
+
+# ✅ 结构化 JSON（可搜索/聚合/告警/关联）
+{"ts":"2024-06-14T10:30:00Z","level":"INFO","service":"order","requestId":"req_abc","userId":"123","action":"order.created","orderId":"456","amount":99.50,"duration_ms":45}
+```
+
+## 必须贯穿的 Request ID
+
+```python
+# 中间件：每个请求生成唯一 requestId，注入所有日志
+@app.middleware("http")
+async def request_id_middleware(request, call_next):
+    request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
+    # 存入 contextvar，所有日志自动带上
+    log_context.set({"requestId": request_id})
+    response = await call_next(request)
+    response.headers["X-Request-ID"] = request_id
+    return response
+
+# 使用时自动带 requestId
+log.info("Order created", orderId="456", amount=99.50)
+# → {"requestId":"req_abc","orderId":"456","amount":99.50,...}
+```
+
+## 日志级别决策树
+
+```
+用户操作成功 → INFO
+预期内的异常（重试/降级） → WARN
+需要人工干预的故障 → ERROR
+开发调试细节 → DEBUG（生产关闭）
+```
+
+## 敏感信息脱敏
+
+```python
+# ❌ 日志泄露密码/token
+log.info("User login", email=email, password=password)  # 泄露！
+
+# ✅ 脱敏
+log.info("User login", email=mask_email(email))  # "j***@example.com"
+# 密码/token 永远不记日志
+```
+
+## 日志聚合架构
+
+```
+应用 → stdout → 容器日志驱动 → Fluent Bit → Loki/Elasticsearch → Grafana/Kibana
+```
+
+**关键原则：**
+- 应用只写 stdout（不直接写文件/网络）
+- 采集器（Fluent Bit）负责转发
+- 查询在 Grafana/Kibana 做
+- 保留策略：ERROR 90 天 / INFO 30 天 / DEBUG 不保留

package/observability/03-checklists/observability-checklist.md

@@ -0,0 +1,54 @@
+---
+id: observability-checklist
+title: 可观测性上线清单
+domain: observability
+category: 03-checklists
+difficulty: beginner
+tags: [observability, checklist, logging, metrics, alerting, health-check, dashboard, distributed-tracing]
+quality_score: 87
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 可观测性上线清单
+
+## 日志
+- [ ] 所有日志是 JSON 结构化格式
+- [ ] 每条日志有 requestId（贯穿请求链路）
+- [ ] 日志级别正确（INFO/WARN/ERROR）
+- [ ] 敏感信息（密码/token/PII）已脱敏
+- [ ] 日志写 stdout（不写文件）
+- [ ] 日志采集器（Fluent Bit/Promtail）已配置
+
+## 指标
+- [ ] 每个端点有 RED 指标（Rate/Errors/Duration）
+- [ ] 数据库连接池使用率有指标
+- [ ] 队列深度有指标（如使用消息队列）
+- [ ] 业务指标定义（注册量/订单量/收入）
+- [ ] 指标暴露在 `/metrics`（Prometheus 格式）
+
+## 告警
+- [ ] 5xx 错误率 > 1% → PagerDuty P1
+- [ ] p95 延迟 > 500ms → PagerDuty P2
+- [ ] 数据库连接池 > 80% → Slack
+- [ ] 磁盘空间 < 10% → PagerDuty P1
+- [ ] 告警有 runbook（怎么处理）
+- [ ] 没有 alert fatigue（误报率 < 5%）
+
+## 健康检查
+- [ ] `/api/health` 返回服务状态 + 依赖检查
+- [ ] 健康检查包含数据库连接测试
+- [ ] 健康检查包含关键依赖测试（Redis/外部API）
+- [ ] 容器编排用健康检查做重启决策
+
+## 仪表盘
+- [ ] 服务总览仪表盘（QPS/延迟/错误率/饱和度）
+- [ ] 业务指标仪表盘（日活/订单/收入）
+- [ ] 基础设施仪表盘（CPU/内存/磁盘/网络）
+- [ ] 仪表盘有阈值标注（绿色/黄色/红色区间）
+
+## 分布式追踪（多服务时）
+- [ ] 请求头传播 traceparent
+- [ ] 数据库查询有 span
+- [ ] 外部 API 调用有 span
+- [ ] span 有关键业务标签（userId/orderId）

package/observability/04-antipatterns/observability-antipatterns.md

@@ -0,0 +1,106 @@
+---
+id: observability-antipatterns
+title: 可观测性反模式（避坑指南）
+domain: observability
+category: 04-antipatterns
+difficulty: intermediate
+tags: [observability, antipattern, logging, metrics, alerting, tracing, dashboard, structured-logging, cardinality, noise]
+quality_score: 87
+maintainer: platform-team@umadev.com
+last_updated: 2024-06-14
+---
+
+# 可观测性反模式（避坑指南）
+
+## 1. 日志里打印敏感数据
+```python
+# ❌ 泄露用户密码 / API key / PII
+logger.info(f"User login: email={email}, password={password}, token={jwt}")
+
+# ✅ 只记非敏感字段，脱敏 PII
+logger.info("User login", email=mask_email(email), auth_method="jwt")
+```
+
+## 2. 高基数指标标签（cardinality bomb）
+```python
+# ❌ userId 做标签 → 每个用户一个时间序列，10 万用户 = 内存爆炸
+metrics.counter("requests", labels={"userId": user_id})
+
+# ✅ 低基数标签（status/method/path），userId 放日志
+metrics.counter("requests", labels={"method": "GET", "status": "200"})
+```
+
+## 3. Alert Fatigue（告警风暴）
+```yaml
+# ❌ 任何 500 都告警 → 每天上百条，团队无视
+alert: http_500
+condition: rate(http_requests{status="500"}[1m]) > 0
+
+# ✅ 错误率超阈值 + 持续时间才告警
+alert: http_500_rate
+condition: |
+  rate(http_requests{status="500"}[5m]) / rate(http_requests[5m]) > 0.01
+for: 5m
+```
+
+## 4. 无 Request ID 关联
+```python
+# ❌ 日志无法关联到同一请求
+logger.info("Received request")
+# ... 50 行后 ...
+logger.info("Database query failed")  # 哪个请求？
+
+# ✅ Request ID 贯穿
+logger.info("Received request", requestId=req_id)
+logger.info("Database query failed", requestId=req_id)  # 可关联！
+```
+
+## 5. 日志当业务数据用
+```python
+# ❌ 从日志里解析订单（日志可能丢/截断/格式变）
+log.info(f"ORDER_CREATED|{order.id}|{order.amount}")
+
+# ✅ 业务事件走数据库/消息队列，日志只做可观测
+db.insert(order)
+event_bus.publish("order.created", order)
+log.info("Order created", orderId=order.id)  # 辅助
+```
+
+## 6. 只看平均延迟
+```
+# ❌ 平均延迟 100ms 看起来很好
+avg = 100ms
+
+# ✅ p95/p99 才反映真实体验
+p50 = 50ms   # 一半请求很快
+p95 = 800ms  # 但 5% 的用户等近 1 秒！
+p99 = 3000ms # 1% 的用户等 3 秒
+```
+
+## 7. 无 dashboard 直接看原始日志
+```
+# ❌ 出事故时 grep 日志（慢、无法聚合、无法看趋势）
+kubectl logs api-server | grep ERROR | wc -l
+
+# ✅ Grafana 仪表盘（实时趋势、错误率曲线、延迟分布）
+```
+
+## 8. 健康检查只返回 200
+```json
+// ❌ 数据库挂了但健康检查还是 200
+GET /health → 200 OK
+
+// ✅ 检查依赖，降级状态
+GET /health → 200, {"db":"ok","redis":"degraded","status":"degraded"}
+GET /health → 503, {"db":"down","status":"unhealthy"}
+```
+
+## 9. 不设日志保留策略
+```
+# ❌ 日志永久保留 → 磁盘满 → 服务挂
+# ✅ 分级保留
+ERROR: 90 天
+WARN:  30 天
+INFO:  14 天
+DEBUG: 不保留（生产关闭）
+```