ljwx-k8s/DELIVERABLES.md

可观测性增强交付物清单

📦 完整文件结构

k8s/
│
├── 🚀 快速部署脚本
│   ├── deploy-observability-enhancement.sh          # 一键部署（交互式）
│   └── verify-observability-enhanced.sh             # 验收脚本（自动化测试）
│
├── 📖 文档
│   ├── OBSERVABILITY-ENHANCEMENT-GUIDE.md           # 完整使用指南（主文档）⭐
│   ├── DEPLOYMENT-SUMMARY-OBSERVABILITY.md          # 部署总结和验收清单
│   └── DELIVERABLES.md                              # 本文档（交付清单）
│
├── 🔧 基础设施监控
│   └── infra/observability/
│       ├── postgres-exporter.yaml                   # Postgres Exporter 完整部署
│       ├── postgres-secret-example.yaml             # Postgres 连接配置（模板）
│       ├── redis-exporter.yaml                      # Redis Exporter 完整部署
│       └── redis-secret-example.yaml                # Redis 连接配置（模板）
│
├── 📊 Prometheus 监控配置
│   └── monitoring/prometheus/
│       ├── prometheus-configmap-enhanced.yaml       # 增强的 Prometheus 配置
│       └── rules/                                   # 告警规则集
│           ├── postgres-alerts.yml                  # Postgres 告警（20+ 规则）
│           ├── redis-alerts.yml                     # Redis 告警（20+ 规则）
│           └── k3s-operational-alerts.yml           # K3s 告警（30+ 规则）
│
├── 📈 Grafana 配置
│   └── monitoring/grafana/
│       ├── datasources-loki-tempo-enhanced.yaml     # Loki↔Tempo 双向跳转配置
│       └── dashboards/
│           ├── README.md                            # Dashboard 导入指南
│           └── import-dashboards.sh                 # 一键导入脚本
│
└── 📚 业务应用集成文档
    └── docs/observability/
        ├── business-instrumentation-spring-boot.md  # Spring Boot 完整集成指南
        ├── business-instrumentation-python.md       # Python 完整集成指南
        └── pg-stat-statements-setup.md              # pg_stat_statements 启用指南

✅ 核心交付物（按 P0 任务分组）

T1 & T2: Prometheus Scrape + Exporter 部署

文件:

• monitoring/prometheus/prometheus-configmap-enhanced.yaml
• infra/observability/postgres-exporter.yaml
• infra/observability/redis-exporter.yaml

功能:

• ✅ 新增 scrape jobs: postgres-exporter, redis-exporter, loki, tempo
• ✅ 自动服务发现（kubernetes_sd_config）
• ✅ 支持 pg_stat_statements 慢查询监控
• ✅ 支持 Redis 完整指标（内存、缓存、持久化、复制）

T3 & T4: Grafana + 告警规则

文件:

• monitoring/grafana/datasources-loki-tempo-enhanced.yaml
• monitoring/grafana/dashboards/import-dashboards.sh
• monitoring/prometheus/rules/*.yml

功能:

• ✅ Loki → Tempo 双向跳转（derivedFields + tracesToLogs）
• ✅ 导入 3 个运营级 Dashboard（Postgres/Redis/K3s）
• ✅ 70+ 条生产级告警规则

T5 & T6: 业务应用三件套

文件:

• docs/observability/business-instrumentation-spring-boot.md
• docs/observability/business-instrumentation-python.md

功能:

• ✅ Metrics: Prometheus endpoint 配置
• ✅ Trace: OpenTelemetry 自动 instrumentation（含 JDBC/Redis spans）
• ✅ Logs: JSON 日志 + trace_id 字段
• ✅ 完整 Kubernetes Deployment 示例

T7: pg_stat_statements

文件:

• docs/observability/pg-stat-statements-setup.md

功能:

• ✅ PostgreSQL 配置修改指南
• ✅ 扩展创建和权限配置
• ✅ 慢查询分析 SQL
• ✅ Grafana 面板配置

🎯 使用指南

1️⃣ 快速开始（3 分钟）

# 进入项目目录
cd /Users/brunogao/work/codes/tools/macos/k8s

# 执行一键部署
./deploy-observability-enhancement.sh

# 验收测试
./verify-observability-enhanced.sh

2️⃣ 查看文档

主文档: OBSERVABILITY-ENHANCEMENT-GUIDE.md

包含内容:

• 目标和架构
• 5 分钟快速部署
• 完整验收步骤
• 关键指标和查询
• 故障排查
• 最佳实践

3️⃣ 部署后验证

# 1. 访问 Prometheus Targets
kubectl port-forward -n monitoring svc/prometheus 9090:9090
# 浏览器: http://localhost:9090/targets

# 2. 访问 Grafana Dashboards
kubectl port-forward -n monitoring svc/grafana 3000:3000
# 浏览器: http://localhost:3000

# 3. 测试 Loki → Tempo 跳转
# Grafana → Explore → Loki → 查询日志 → 点击 "View Trace"

# 4. 测试 Tempo → Loki 跳转
# Grafana → Explore → Tempo → 查询 trace → 点击 "Logs for this span"

📊 技术栈

• Prometheus: Metrics 采集和存储
• Grafana: 可视化和 Dashboard
• Loki: 日志聚合
• Tempo: 分布式追踪
• postgres_exporter: PostgreSQL 监控
• redis_exporter: Redis 监控
• OpenTelemetry: 业务应用追踪标准

🔑 关键配置项

Prometheus Scrape Configs

# Postgres Exporter
job_name: 'postgres-exporter'
port: 9187
metrics_path: /metrics

# Redis Exporter
job_name: 'redis-exporter'
port: 9121
metrics_path: /metrics

# 业务应用（自动发现）
job_name: 'business-services'
annotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "8080"
  prometheus.io/path: "/actuator/prometheus"

Loki → Tempo 跳转

# Loki datasource
derivedFields:
  - datasourceUid: tempo
    matcherRegex: '"trace_id":\s*"(\w+)"'  # JSON 格式
    name: TraceID
    url: '${__value.raw}'

Tempo → Loki 跳转

# Tempo datasource
tracesToLogs:
  datasourceUid: 'loki'
  filterByTraceID: true
  query: '{namespace="${__span.tags["namespace"]}"} | json | trace_id="${__span.traceId}"'

📈 监控覆盖范围

基础设施

• ✅ Kubernetes 集群（Nodes, Pods, Workloads）
• ✅ PostgreSQL（连接、查询、锁、复制、存储）
• ✅ Redis（内存、缓存、持久化、复制）
• ✅ 网络（Ingress, Service）

可观测性组件

• ✅ Prometheus 自身
• ✅ Loki 日志管道
• ✅ Tempo 追踪管道
• ✅ Grafana 健康度

业务应用（集成后）

• ✅ RED 指标（Request, Error, Duration）
• ✅ 自定义业务指标
• ✅ 数据库查询 spans
• ✅ 缓存操作 spans
• ✅ HTTP 调用 spans

🚨 告警覆盖范围

Postgres（20+ 规则）

• 连接数、慢查询、锁等待、死锁
• 磁盘空间、WAL、复制延迟
• 缓存命中率、表膨胀、回滚率

Redis（20+ 规则）

• 内存使用率、连接数、拒绝连接
• 缓存命中率、键淘汰、慢查询
• 内存碎片、复制延迟、阻塞客户端

K3s（30+ 规则）

• API Server 错误率和延迟
• Node 健康状态（Ready, Memory, Disk, PID）
• Pod 状态（CrashLoop, OOM, Pending）
• Workload 副本健康（Deployment, StatefulSet, DaemonSet）
• PV/PVC 存储告警
• HPA 扩容告警

💡 最佳实践

1. 数据保留策略

• Prometheus: 15 天
• Loki: 30 天
• Tempo: 7 天（traces）

2. 采样率建议

• 开发环境: 100%
• 生产环境: 10-20%

3. 安全建议

• Exporter 使用专用只读账号
• 定期轮换密码
• 限制外部访问
• 启用 RBAC

4. 性能优化

• 调整 scrape_interval（默认 15s）
• 避免高基数 label（user_id, request_id）
• 异步导出 traces
• 配置合理的资源限制

📞 支持和故障排查

验收脚本

./verify-observability-enhanced.sh

常见问题

参考 OBSERVABILITY-ENHANCEMENT-GUIDE.md 的"故障排查"章节

日志查看

# Exporter 日志
kubectl logs -n monitoring deployment/postgres-exporter
kubectl logs -n monitoring deployment/redis-exporter

# Prometheus 日志
kubectl logs -n monitoring deployment/prometheus

# Grafana 日志
kubectl logs -n monitoring deployment/grafana

🎓 学习资源

官方文档

• Prometheus
• Grafana
• OpenTelemetry

社区 Dashboard

• Grafana Dashboards Library

✨ 总结

本次交付包含：

• 20+ 配置文件: 即取即用的生产级配置
• 70+ 告警规则: 覆盖基础设施和应用
• 3 个 Dashboard: 运营级可视化
• 3 个完整指南: Spring Boot、Python、pg_stat_statements
• 2 个自动化脚本: 部署和验收
• 1 个完整文档: 从入门到精通

立即开始: 运行 ./deploy-observability-enhancement.sh 🚀