@umacloud/knowledge 1.0.1

package/operations/observability-complete.md

@@ -0,0 +1,442 @@
+---
+id: observability-complete
+title: observability-complete
+domain: operations
+category: observability-complete.md
+difficulty: intermediate
+tags: [complete, dashboard, observability, operations, 告警设计, 实施清单, 常见失败模式, 技术选型]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+# 功能：可观测性完整体系
+# 作用：提供日志、指标、追踪三大支柱的完整实施指南
+# 创建时间：2026-03-20
+# 最后修改：2026-03-20
+
+## 目标
+建立生产环境全链路可观测能力,实现故障快速定位、性能瓶颈精准识别、用户体验量化评估。
+
+## 适用范围
+- 生产环境所有微服务、数据库、中间件、基础设施
+- 关键业务流程的端到端追踪
+- 多云、混合云环境的统一观测
+
+## 核心概念：三支柱
+
+### 1. 日志（Logs）
+**定义**：离散的、带时间戳的事件记录
+
+**日志分级**：
+- ERROR：系统错误、异常、需要立即处理
+- WARN：潜在问题、降级、接近阈值
+- INFO：关键业务流程、状态变更
+- DEBUG：调试信息（生产环境默认关闭）
+- TRACE：详细执行路径（仅用于故障诊断）
+
+**结构化日志规范**：
+```json
+{
+  "timestamp": "2026-03-20T10:30:45.123Z",
+  "level": "ERROR",
+  "service": "order-service",
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "user_id": "user_789",
+  "message": "Payment processing failed",
+  "error": {
+    "type": "PaymentGatewayException",
+    "code": "GATEWAY_TIMEOUT",
+    "stack": "..."
+  },
+  "context": {
+    "order_id": "order_123",
+    "amount": 99.99,
+    "currency": "CNY"
+  },
+  "environment": "production",
+  "version": "2.1.3"
+}
+```
+
+**日志采集策略**：
+- 使用 Fluentd/Fluent Bit/Filebeat 采集容器/主机日志
+- 统一输出到 Elasticsearch/Loki
+- 保留策略：ERROR/WARN 保留 90 天,INFO 保留 30 天,DEBUG/TRACE 仅故障时临时开启
+- 采样策略：高流量场景按 10% 采样 INFO 日志,ERROR/WARN 必须 100% 采集
+
+**日志查询最佳实践**：
+```bash
+# 查询某个 trace_id 的全链路日志
+trace_id:"abc123"
+
+# 查询某个服务的错误日志
+service:"order-service" AND level:"ERROR"
+
+# 查询特定用户的操作日志
+user_id:"user_789" AND level:("INFO" OR "ERROR")
+
+# 聚合分析：按错误类型分组
+level:"ERROR" | stats count by error.type
+```
+
+### 2. 指标（Metrics）
+**定义**：可聚合的、数值化的系统状态测量
+
+**指标类型**：
+- Counter（计数器）：单调递增（如请求总数、错误总数）
+- Gauge（仪表）：可增可减（如当前连接数、内存使用）
+- Histogram（直方图）：分布统计（如请求延迟、响应大小）
+- Summary（摘要）：分位数统计（如 P50/P95/P99 延迟）
+
+**RED 指标（请求驱动服务）**：
+- Rate（请求速率）：每秒请求数（RPS）
+- Errors（错误率）：失败请求占比（4xx/5xx/超时）
+- Duration（延迟）：请求处理时间分布（P50/P95/P99）
+
+**USE 指标（资源）**：
+- Utilization（利用率）：资源使用百分比（CPU/内存/磁盘/网络）
+- Saturation（饱和度）：排队/等待程度（负载均值、运行队列）
+- Errors（错误）：错误事件计数（网络错误、磁盘错误）
+
+**核心业务指标**：
+```yaml
+# 电商交易系统
+- 订单创建成功率
+- 支付成功率
+- 订单履约时长（P95/P99）
+- 库存准确率
+- 购物车转化率
+
+# 用户系统
+- 登录成功率
+- API 响应时间（P95/P99）
+- 活跃用户数（DAU/MAU）
+- 用户留存率
+
+# 基础设施
+- 容器 CPU 使用率
+- 容器内存使用率
+- 网络吞吐量
+- 磁盘 I/O 延迟
+- 数据库连接池使用率
+```
+
+**指标采集架构**：
+```
+应用（Prometheus SDK）
+  -> Prometheus Server（Pull 模式）
+  -> Remote Write（长期存储）
+  -> Grafana（可视化）
+  -> Alertmanager（告警）
+```
+
+**PromQL 查询示例**：
+```promql
+# HTTP 请求错误率
+sum(rate(http_requests_total{status=~"5.."}[5m])) /
+sum(rate(http_requests_total[5m])) * 100
+
+# P95 延迟
+histogram_quantile(0.95,
+  sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
+)
+
+# 容器内存使用率
+container_memory_usage_bytes{container="order-service"} /
+container_spec_memory_limit_bytes{container="order-service"} * 100
+
+# 预测磁盘空间耗尽时间
+predict_linear(node_filesystem_free_bytes[1h], 4*3600)
+```
+
+### 3. 追踪（Traces）
+**定义**：请求在分布式系统中的完整执行路径
+
+**核心概念**：
+- Trace（追踪）：一次请求的完整旅程
+- Span（跨度）：单个服务的处理单元
+- Span Context：跨服务传递的上下文（trace_id、span_id、baggage）
+
+**分布式追踪实现**：
+```python
+# Python OpenTelemetry 示例
+from opentelemetry import trace
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+tracer = trace.get_tracer(__name__)
+
+@app.route("/checkout")
+def checkout():
+    with tracer.start_as_current_span("checkout") as span:
+        span.set_attribute("user_id", user_id)
+        span.set_attribute("order_id", order_id)
+
+        # 调用支付服务
+        with tracer.start_span("call_payment_service"):
+            payment_result = payment_service.charge()
+
+        # 调用库存服务
+        with tracer.start_span("call_inventory_service"):
+            inventory_result = inventory_service.reserve()
+
+        return {"status": "success"}
+```
+
+**追踪采样策略**：
+- 头部采样：在 Trace 开始时决定是否采样（概率采样）
+- 尾部采样：在 Trace 结束后根据规则决定是否保留（错误/慢请求必留）
+- 混合策略：正常流量 1% 采样,错误/慢请求 100% 保留
+
+**追踪分析场景**：
+- 调用链路可视化：识别关键路径和瓶颈服务
+- 依赖关系图：自动生成服务拓扑
+- 性能热点分析：定位耗时最长的 Span
+- 错误传播追踪：查看错误在调用链中的传播路径
+
+## 技术选型
+
+### 日志系统
+**方案对比**：
+| 系统 | 优势 | 劣势 | 适用场景 |
+|------|------|------|----------|
+| Elasticsearch + Kibana (ELK) | 功能完整、生态成熟 | 资源消耗大、查询慢 | 大规模日志分析 |
+| Loki + Grafana | 轻量级、与 Prometheus 统一 | 查询能力有限 | 中小规模、成本敏感 |
+| Splunk | 企业级功能、可视化强 | 费用高昂 | 企业级生产环境 |
+
+**推荐方案**：
+- 中小团队：Loki + Grafana（与监控统一）
+- 大型团队：Elasticsearch + Kibana（功能完整）
+
+### 指标系统
+**方案对比**：
+| 系统 | 优势 | 劣势 | 适用场景 |
+|------|------|------|----------|
+| Prometheus + Grafana | 开源标准、查询强大 | 单机存储、高可用需额外方案 | 通用监控 |
+| VictoriaMetrics | 高性能、长期存储 | 社区较小 | 大规模时序数据 |
+| Datadog | SaaS、全栈监控 | 费用高 | 企业级快速落地 |
+| InfluxDB | 高性能写入 | 生态不如 Prometheus | IoT/实时分析 |
+
+**推荐方案**：
+- 自建：Prometheus + Thanos/Cortex（长期存储+高可用）
+- SaaS：Datadog/Dynatrace（快速落地）
+
+### 追踪系统
+**方案对比**：
+| 系统 | 优势 | 劣势 | 适用场景 |
+|------|------|------|----------|
+| Jaeger | 开源标准、Uber 出品 | UI 较简陋 | 微服务追踪 |
+| Zipkin | 轻量级、易上手 | 功能较少 | 中小规模 |
+| Tempo + Grafana | 与 Loki/Prometheus 统一 | 功能较新 | 统一可观测性 |
+| SkyWalking | APM 功能强、对应用无侵入 | 社区较小 | Java/PHP 应用 |
+
+**推荐方案**：
+- 云原生：Jaeger + OpenTelemetry（标准化）
+- 统一平台：Grafana Tempo（与日志/指标统一）
+
+## 实施清单
+
+### 阶段一：基础覆盖（0-1个月）
+- [ ] 部署日志采集（Fluentd/Filebeat -> Elasticsearch/Loki）
+- [ ] 部署指标采集（Prometheus + Node Exporter + 应用 SDK）
+- [ ] 部署追踪系统（Jaeger/Tempo + OpenTelemetry SDK）
+- [ ] 创建基础 Dashboard：
+  - 服务健康状态（UP/DOWN）
+  - 核心业务指标（QPS、错误率、延迟）
+  - 基础设施指标（CPU、内存、磁盘、网络）
+- [ ] 配置基础告警规则（服务宕机、错误率飙升、磁盘空间不足）
+
+### 阶段二：深度集成（1-3个月）
+- [ ] 应用层埋点：
+  - HTTP/API 请求指标
+  - 数据库查询指标
+  - 缓存命中率
+  - 外部服务调用指标
+- [ ] 分布式追踪集成：
+  - 跨服务 Trace Context 传递
+  - 数据库/缓存/消息队列 Span 插桩
+  - 错误 Span 自动标记
+- [ ] 结构化日志改造：
+  - 统一日志格式（JSON）
+  - 注入 Trace Context（trace_id/span_id）
+  - 敏感信息脱敏
+- [ ] Dashboard 体系化：
+  - 业务大屏（转化率、营收、活跃用户）
+  - 技术大屏（SLI/SLO、容量、成本）
+  - 值班大屏（告警、事件、值班人员）
+
+### 阶段三：智能化运维（3-6个月）
+- [ ] 异常检测：
+  - 基于历史数据的动态阈值
+  - AI/ML 异常检测算法
+- [ ] 容量预测：
+  - 资源使用趋势预测
+  - 自动扩缩容建议
+- [ ] 根因分析：
+  - 日志/指标/追踪联动分析
+  - 自动化故障诊断报告
+- [ ] AIOps 集成：
+  - 智能告警降噪
+  - 自动故障恢复（自愈）
+
+## 告警设计
+
+### 告警分级
+- P0（紧急）：核心业务中断、数据丢失风险
+  - 响应时间：<5 分钟
+  - 通知方式：电话 + 短信 + IM
+- P1（严重）：部分功能降级、性能严重下降
+  - 响应时间：<15 分钟
+  - 通知方式：短信 + IM
+- P2（警告）：潜在风险、资源接近阈值
+  - 响应时间：<1 小时
+  - 通知方式：IM + 邮件
+- P3（通知）：非紧急、可延后处理
+  - 响应时间：<24 小时
+  - 通知方式：邮件
+
+### 告警规则示例
+```yaml
+# 服务可用性告警
+- alert: ServiceDown
+  expr: up{job="order-service"} == 0
+  for: 2m
+  labels:
+    severity: P0
+  annotations:
+    summary: "服务宕机：{{ $labels.job }}"
+    description: "服务 {{ $labels.instance }} 已宕机超过 2 分钟"
+
+# 错误率告警
+- alert: HighErrorRate
+  expr: |
+    sum(rate(http_requests_total{status=~"5.."}[5m])) by (service) /
+    sum(rate(http_requests_total[5m])) by (service) > 0.05
+  for: 5m
+  labels:
+    severity: P1
+  annotations:
+    summary: "服务 {{ $labels.service }} 错误率过高"
+    description: "错误率 {{ $value | humanizePercentage }} 超过 5% 阈值"
+
+# 延迟告警
+- alert: HighLatency
+  expr: |
+    histogram_quantile(0.95,
+      sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service)
+    ) > 2
+  for: 10m
+  labels:
+    severity: P1
+  annotations:
+    summary: "服务 {{ $labels.service }} P95 延迟过高"
+    description: "P95 延迟 {{ $value }} 秒超过 2 秒阈值"
+```
+
+### 告警降噪
+- 分组（Grouping）：相关告警合并通知
+- 抑制（Inhibition）：高优先级告警抑制低优先级
+- 静默（Silencing）：计划内维护期间静默告警
+- 去重（Deduplication）：相同告警去重,避免刷屏
+
+## Dashboard 设计原则
+
+### 信息层次
+1. **L1 - 业务视角**：业务健康度、用户体验、核心 KPI
+2. **L2 - 服务视角**：服务 SLI/SLO、错误率、延迟、吞吐
+3. **L3 - 基础设施视角**：CPU、内存、磁盘、网络、中间件
+4. **L4 - 详细视图**：日志、追踪、调试信息
+
+### 可视化最佳实践
+- 使用颜色编码：绿色（健康）、黄色（警告）、红色（异常）
+- 添加阈值线：清晰标识正常/警告/异常区间
+- 时间范围选择器：支持 1h/6h/24h/7d/30d 快速切换
+- 变量联动：支持按服务/环境/版本筛选
+- 图表注释：在关键事件（部署、故障、扩容）处添加注释
+
+### Dashboard 模板
+```yaml
+# 服务健康 Dashboard
+- 标题：服务健康概览
+  面板：
+    - 服务状态（Stat 面板）
+    - QPS（Time Series）
+    - 错误率（Time Series）
+    - P95/P99 延迟（Time Series）
+    - 活跃实例数（Gauge）
+    - 最近告警列表（Table）
+```
+
+## 常见失败模式
+
+### 1. 日志问题
+- **日志过多导致存储成本失控**：未做采样、DEBUG 日志全量保留
+- **日志格式不统一**：多团队各自定义格式,无法统一查询
+- **敏感信息泄露**：未脱敏,日志中包含密码、密钥、个人信息
+- **缺少 Trace Context**：无法关联日志与追踪,排查效率低
+
+### 2. 指标问题
+- **指标爆炸**：高基数标签（如 user_id、request_id）导致 TSDB 性能下降
+- **缺少业务指标**：只有技术指标,无法反映业务健康度
+- **告警风暴**：阈值设置不当、缺少降噪,导致告警疲劳
+- **Dashboard 过多过乱**：缺少层次和治理,找不到关键信息
+
+### 3. 追踪问题
+- **采样率设置不当**：正常请求采样过低,关键错误追踪丢失
+- **Span 粒度过粗**：缺少关键步骤的 Span,无法定位瓶颈
+- **Trace Context 丢失**：跨服务传递失败,追踪链路断裂
+- **追踪数据保留时间过短**：历史问题无法回溯
+
+### 4. 系统性问题
+- **可观测性孤岛**：日志/指标/追踪三套独立系统,无法联动
+- **缺少文档和培训**：团队成员不会使用,可观测性价值未释放
+- **成本失控**：未做资源规划和优化,存储/查询成本过高
+- **忽视性能影响**：可观测性组件自身成为性能瓶颈
+
+## 验收标准
+
+### 功能验收
+- [ ] 所有服务日志采集覆盖 100%
+- [ ] 所有服务核心指标（RED/USE）覆盖 100%
+- [ ] 所有服务分布式追踪集成 100%
+- [ ] 关键业务流程端到端追踪可见
+- [ ] 日志/指标/追踪可通过 Trace Context 关联
+
+### 性能验收
+- [ ] 日志采集延迟 < 10 秒
+- [ ] 指标采集延迟 < 30 秒
+- [ ] 追踪采集延迟 < 60 秒
+- [ ] Dashboard 加载时间 < 5 秒
+- [ ] 查询响应时间 < 10 秒（90% 请求）
+
+### 成本验收
+- [ ] 日志存储成本 < $X/GB/月
+- [ ] 指标存储成本 < $Y/百万样本/月
+- [ ] 追踪存储成本 < $Z/百万 Span/月
+- [ ] 可观测性总成本占基础设施成本 < 10%
+
+### 可用性验收
+- [ ] 日志系统可用性 >= 99.9%
+- [ ] 指标系统可用性 >= 99.9%
+- [ ] 追踪系统可用性 >= 99.5%
+- [ ] 数据保留符合合规要求
+
+## 参考资源
+
+### 开源工具
+- OpenTelemetry：统一可观测性标准 https://opentelemetry.io/
+- Prometheus：指标采集与告警 https://prometheus.io/
+- Grafana：统一可视化平台 https://grafana.com/
+- Jaeger：分布式追踪 https://www.jaegertracing.io/
+- Fluentd：日志采集 https://www.fluentd.org/
+
+### 最佳实践
+- Google SRE Book：https://sre.google/books/
+- Observability Engineering（O'Reilly）
+- Distributed Tracing in Practice（O'Reilly）
+
+### 云服务
+- AWS X-Ray、CloudWatch
+- Azure Monitor、Application Insights
+- Google Cloud Operations Suite
+- Datadog、Dynatrace、New Relic