# 可观测性增强交付物清单

## 📦 完整文件结构

```
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 分钟）

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

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

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

### 2️⃣ 查看文档

**主文档**: [OBSERVABILITY-ENHANCEMENT-GUIDE.md](./OBSERVABILITY-ENHANCEMENT-GUIDE.md)

**包含内容**:
- 目标和架构
- 5 分钟快速部署
- 完整验收步骤
- 关键指标和查询
- 故障排查
- 最佳实践

### 3️⃣ 部署后验证

```bash
# 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

```yaml
# 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 跳转

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

### Tempo → Loki 跳转

```yaml
# 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
- 配置合理的资源限制

## 📞 支持和故障排查

### 验收脚本
```bash
./verify-observability-enhanced.sh
```

### 常见问题
参考 [OBSERVABILITY-ENHANCEMENT-GUIDE.md](./OBSERVABILITY-ENHANCEMENT-GUIDE.md) 的"故障排查"章节

### 日志查看
```bash
# 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](https://prometheus.io/docs/)
- [Grafana](https://grafana.com/docs/)
- [OpenTelemetry](https://opentelemetry.io/docs/)

### 社区 Dashboard
- [Grafana Dashboards Library](https://grafana.com/grafana/dashboards/)

## ✨ 总结

本次交付包含：

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

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