gao/ljwx-k8s

Fork 0

Files

T

bruno 2a56d7fd6c first commit

2026-02-20 22:50:45 +08:00

11 KiB

Raw Permalink Blame History

可观测性增强部署总结

完成时间: 2025-12-19 任务: K8s 原生 Prometheus 监控增强 + Postgres/Redis/K3s 监控 + Loki↔Tempo 链路追踪

✅ 交付清单

📦 P0 核心交付物

T1 & T2: Exporter 部署

文件	说明
`infra/observability/postgres-exporter.yaml`	Postgres Exporter Deployment + Service + Queries ConfigMap
`infra/observability/postgres-secret-example.yaml`	Postgres 连接配置示例（需修改）
`infra/observability/redis-exporter.yaml`	Redis Exporter Deployment + Service
`infra/observability/redis-secret-example.yaml`	Redis 连接配置示例（需修改）

特性：

✅ 支持 pg_stat_statements 慢查询分析
✅ 支持 Postgres 锁、复制、表膨胀监控
✅ 支持 Redis 内存、缓存命中、键淘汰监控
✅ 自动服务发现（Prometheus kubernetes_sd_config）

T1 & T3 & T4: Prometheus 配置增强

文件	说明
`monitoring/prometheus/prometheus-configmap-enhanced.yaml`	增强的 Prometheus 配置（新增 scrape configs）
`monitoring/prometheus/rules/postgres-alerts.yml`	Postgres 告警规则（20+ 条）
`monitoring/prometheus/rules/redis-alerts.yml`	Redis 告警规则（20+ 条）
`monitoring/prometheus/rules/k3s-operational-alerts.yml`	K3s 运营告警规则（30+ 条）

新增 Scrape Jobs：

postgres-exporter: 通过 Service label 自动发现
redis-exporter: 通过 Service label 自动发现
loki: 静态配置 Loki 自监控
tempo: 静态配置 Tempo 自监控
business-services: 支持业务应用通过 annotation 自动发现

T4: Grafana Loki ↔ Tempo 双向跳转

文件	说明
`monitoring/grafana/datasources-loki-tempo-enhanced.yaml`	增强的数据源配置

特性：

✅ Loki → Tempo: 支持 JSON、KV、灵活格式的 trace_id 提取
✅ Tempo → Loki: 自动关联 namespace/pod/container 查询日志
✅ Tempo → Prometheus: 关联 RED 指标（Request Rate/Error Rate/Duration）
✅ 统一字段名：trace_id（避免 traceId/traceID 混用）

T3: Grafana Dashboards

文件	说明
`monitoring/grafana/dashboards/README.md`	Dashboard 导入指南 + 关键查询
`monitoring/grafana/dashboards/import-dashboards.sh`	一键导入脚本

导入的 Dashboards：

PostgreSQL Database (ID: 9628): 连接/慢查询/锁/IO/WAL
Redis (ID: 11835): 内存/缓存/持久化/复制
Kubernetes Cluster Monitoring (ID: 15760): Pod/Node/资源/告警

T5 & T6: 业务应用集成文档

文件	说明
`docs/observability/business-instrumentation-spring-boot.md`	Spring Boot 完整集成指南
`docs/observability/business-instrumentation-python.md`	Python (Flask/FastAPI) 完整集成指南

覆盖内容：

✅ Metrics: Micrometer/prometheus-client 配置
✅ Trace: OpenTelemetry 自动 instrumentation（包含 JDBC/Redis spans）
✅ Logs: JSON 日志 + trace_id 字段
✅ Kubernetes Deployment 完整示例
✅ 验收步骤和常见问题

T7: pg_stat_statements 启用文档

文件	说明
`docs/observability/pg-stat-statements-setup.md`	pg_stat_statements 启用和配置指南

覆盖内容：

✅ PostgreSQL 配置修改
✅ 扩展创建和权限配置
✅ Exporter 集成
✅ 慢查询分析 SQL 示例
✅ Grafana 面板配置

🔧 工具和脚本

文件	说明
`deploy-observability-enhancement.sh`	一键部署脚本（交互式）
`verify-observability-enhanced.sh`	验收脚本（自动化测试）
`OBSERVABILITY-ENHANCEMENT-GUIDE.md`	完整使用指南（快速开始）
`DEPLOYMENT-SUMMARY-OBSERVABILITY.md`	本文档（交付清单）

🚀 快速部署（3 分钟）

方式1: 一键部署（推荐）

cd /Users/brunogao/work/codes/tools/macos/k8s
./deploy-observability-enhancement.sh

方式2: 手动部署

# 1. 部署 Exporters
kubectl apply -f infra/observability/postgres-secret-example.yaml  # 先修改连接串
kubectl apply -f infra/observability/postgres-exporter.yaml
kubectl apply -f infra/observability/redis-secret-example.yaml     # 先修改连接串
kubectl apply -f infra/observability/redis-exporter.yaml

# 2. 更新 Prometheus
kubectl apply -f monitoring/prometheus/prometheus-configmap-enhanced.yaml
kubectl create configmap prometheus-rules-postgres \
  --from-file=monitoring/prometheus/rules/postgres-alerts.yml \
  -n monitoring --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/prometheus -n monitoring

# 3. 更新 Grafana
kubectl apply -f monitoring/grafana/datasources-loki-tempo-enhanced.yaml
kubectl rollout restart deployment/grafana -n monitoring

# 4. 导入 Dashboards
cd monitoring/grafana/dashboards && ./import-dashboards.sh

# 5. 验收
./verify-observability-enhanced.sh

📊 验收结果

运行验收脚本后，应该看到以下通过项：

✅ 核心组件

Prometheus Running
Grafana Running
Loki Running
Tempo Running

✅ Exporter 部署

postgres-exporter Pod Running
postgres-exporter Service 存在
postgres-exporter Metrics Endpoint 可访问 (:9187/metrics)
redis-exporter Pod Running
redis-exporter Service 存在
redis-exporter Metrics Endpoint 可访问 (:9121/metrics)

✅ Prometheus 抓取

Target postgres-exporter UP
Target redis-exporter UP
Target node-exporter UP
Target kube-state-metrics UP
告警规则已加载

✅ Grafana 配置

Datasource Prometheus 已配置
Datasource Loki 已配置（含 derivedFields）
Datasource Tempo 已配置（含 tracesToLogs）
Dashboard 已导入（PostgreSQL/Redis/K8s）

✅ Loki ↔ Tempo 集成

Loki → Tempo 跳转配置（derivedFields 正则匹配 trace_id）
Tempo → Loki 跳转配置（tracesToLogs 查询）
字段统一为 trace_id

📈 关键指标验证

Postgres

# Prometheus 查询
kubectl port-forward -n monitoring svc/prometheus 9090:9090
# 访问: http://localhost:9090

# 执行查询:
pg_up                                            # Postgres 可用性
pg_stat_database_numbackends                     # 连接数
pg_stat_statements_mean_exec_time                # 慢查询
pg_replication_lag_bytes                         # 复制延迟

Redis

# 执行查询:
redis_up                                         # Redis 可用性
redis_connected_clients                          # 连接数
redis_memory_used_bytes / redis_memory_max_bytes # 内存使用率
redis_keyspace_hits_total / (redis_keyspace_hits_total + redis_keyspace_misses_total) # 命中率

K3s

# 执行查询:
kube_pod_container_status_restarts_total         # Pod 重启
kube_node_status_condition{condition="Ready"}    # Node 状态
kubelet_volume_stats_used_bytes / kubelet_volume_stats_capacity_bytes # PVC 使用率

🔍 故障排查

常见问题

1. Exporter 无数据

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

# 常见原因:
# - Secret 中的连接串错误
# - 数据库/Redis 未部署或无法访问
# - 权限不足（Postgres 需要 pg_monitor 角色）

2. Prometheus Target DOWN

# 检查 Service
kubectl get svc -n monitoring postgres-exporter redis-exporter

# 检查 Endpoint
kubectl get endpoints -n monitoring postgres-exporter redis-exporter

# 检查 Prometheus ConfigMap
kubectl get cm prometheus-config -n monitoring -o yaml | grep -A 20 postgres-exporter

3. Grafana Dashboard 无数据

# 检查数据源连接
# Grafana UI → Configuration → Data Sources → Prometheus → Save & Test

# 检查 Prometheus 是否有数据
curl -s 'http://prometheus.monitoring.svc.cluster.local:9090/api/v1/query?query=up{job="postgres-exporter"}' | jq

4. Loki ↔ Tempo 跳转失败

# 检查日志是否包含 trace_id
kubectl logs -n default <pod-name> | grep trace_id

# 检查 Grafana datasource 配置
kubectl get cm grafana-datasources -n monitoring -o yaml | grep -A 10 derivedFields

# 重新加载 Grafana 配置
kubectl rollout restart deployment/grafana -n monitoring

🎯 后续优化建议

1. 性能优化

调整 Prometheus scrape_interval（根据实际需求）
设置 trace 采样率（生产环境 10-20%）
配置数据保留策略（Prometheus 15 天，Loki 30 天，Tempo 7 天）

2. 安全加固

Exporter 使用专用只读账号
定期轮换密码
限制 Grafana 访问（Ingress + Auth）
启用 Prometheus RBAC

3. 告警优化

配置 Alertmanager 路由和分组
设置告警抑制规则（避免告警风暴）
集成通知渠道（钉钉/企微/Slack）
定义 SLA/SLO 告警

4. 业务监控

部署业务应用（参考 Spring Boot/Python 指南）
验证 metrics/traces/logs 三件套
创建业务 Dashboard
设置业务告警（API 错误率、延迟等）

📚 参考文档

完整指南

OBSERVABILITY-ENHANCEMENT-GUIDE.md - 完整使用指南

组件配置

业务集成

告警规则

📞 支持

如有问题，请：

先运行验收脚本诊断: ./verify-observability-enhanced.sh
查看日志: kubectl logs -n monitoring <pod-name>
参考故障排查文档

部署完成！ 🎉

现在你拥有：

✅ 完整的基础设施监控（Postgres/Redis/K3s）
✅ 生产级告警规则（60+ 条）
✅ 可视化 Dashboard（Grafana）
✅ 分布式链路追踪（Loki ↔ Tempo）
✅ 业务应用集成指南（Spring Boot/Python）

下一步: 开始集成业务应用，验证 metrics/traces/logs 三件套！

11 KiB Raw Permalink Blame History Unescape Escape

可观测性增强部署总结

✅ 交付清单

📦 P0 核心交付物

T1 & T2: Exporter 部署

T1 & T3 & T4: Prometheus 配置增强

T4: Grafana Loki ↔ Tempo 双向跳转

T3: Grafana Dashboards

T5 & T6: 业务应用集成文档

T7: pg_stat_statements 启用文档

🔧 工具和脚本

🚀 快速部署（3 分钟）

方式1: 一键部署（推荐）

方式2: 手动部署

📊 验收结果

✅ 核心组件

✅ Exporter 部署

✅ Prometheus 抓取

✅ Grafana 配置

✅ Loki ↔ Tempo 集成

📈 关键指标验证

Postgres

Redis

K3s

🔍 故障排查

常见问题

1. Exporter 无数据

2. Prometheus Target DOWN

3. Grafana Dashboard 无数据

4. Loki ↔ Tempo 跳转失败

🎯 后续优化建议

1. 性能优化

2. 安全加固

3. 告警优化

4. 业务监控

📚 参考文档

完整指南

组件配置

业务集成

告警规则

📞 支持

11 KiB

Raw Permalink Blame History