12 KiB
12 KiB
Kubernetes 完整可观测性方案
📋 项目概述
本项目为 Kubernetes 集群部署了完整的可观测性栈，包括 Metrics（指标）、Logs（日志） 和 Traces（链路追踪） 三大支柱，实现了生产级别的监控、告警和故障排查能力。
🏗️ 架构组件
┌─────────────────────────────────────────────────────────────────┐
│ Grafana │
│ (统一可视化平台) │
│ http://localhost:30300 │
└────────────┬──────────────┬──────────────┬──────────────────────┘
│ │ │
┌────────▼────────┐ ┌──▼──────┐ ┌─────▼──────┐
│ Prometheus │ │ Loki │ │ Tempo │
│ (Metrics) │ │ (Logs) │ │ (Traces) │
│ :9090 │ │ :3100 │ │ :3200 │
└────────┬────────┘ └──┬──────┘ └─────┬──────┘
│ │ │
┌────────▼────────┐ ┌──▼──────┐ ┌─────▼──────┐
│ Exporters: │ │Promtail │ │ OTel │
│ - node │ │(DaemonS)│ │ Collector │
│ - kube-state │ │ │ │ │
└─────────────────┘ └─────────┘ └────────────┘
│ │ │
┌────────▼──────────────▼──────────────▼──────┐
│ Kubernetes Cluster │
│ (Pods, Nodes, Services...) │
└──────────────────────────────────────────────┘
Metrics（指标监控）- namespace: monitoring
- Prometheus: 时序数据库，存储和查询指标
- Grafana: 可视化平台，仪表盘和告警
- Alertmanager: 告警路由和通知
- kube-state-metrics: Kubernetes 对象状态指标
- node-exporter: 节点级别系统指标（CPU、内存、磁盘、网络）
Logs（日志聚合）- namespace: logging
- Loki: 日志聚合和存储引擎
- Promtail: 日志采集 DaemonSet，自动采集所有 pod 日志
Traces（链路追踪）- namespace: tracing
- Tempo: 分布式追踪后端，存储和查询 traces
- OpenTelemetry Collector: 统一的遥测数据采集和转发
🚀 快速开始
1. 验证部署状态
./verify-observability.sh
2. 访问 Grafana
open http://localhost:30300
# 默认凭据: admin/admin
3. 导入推荐仪表盘
在 Grafana 中点击 Dashboards → New → Import，输入以下 ID：
必备仪表盘：
- 1860 - Node Exporter Full（节点监控）
- 15758 - Kubernetes Views Pods（Pod 监控）
- 13639 - Logs / App（应用日志）
- 315 - Kubernetes cluster monitoring（集群监控）
4. 查看日志（Grafana Explore）
# 查看所有日志
{namespace=~".+"}
# 查看特定应用日志
{namespace="fastapi", pod=~".*"}
# 查看错误日志
{namespace="fastapi"} |= "ERROR"
# 从日志跳转到 trace（如果日志包含 trace_id）
{namespace="fastapi"} | json | trace_id != ""
5. 访问 Prometheus
open http://localhost:30900
📊 核心功能
✅ 已实现功能
1. 完整的 Metrics 监控
- ✅ 集群级别监控（CPU、内存、磁盘、网络）
- ✅ 节点级别监控（系统资源、容器运行时）
- ✅ Pod 级别监控（资源使用、重启、状态）
- ✅ Workload 监控（Deployment、StatefulSet、DaemonSet、Job）
- ✅ 自定义告警规则（15+ 条告警规则）
2. 集中式日志管理
- ✅ 自动采集所有 pod 日志（Promtail DaemonSet）
- ✅ 支持 LogQL 查询语言
- ✅ 日志到 Trace 的关联跳转
- ✅ 日志标签自动提取（namespace、pod、container、app 等）
3. 分布式链路追踪
- ✅ 支持多种协议（OTLP、Jaeger、Zipkin）
- ✅ Trace 到 Logs 的关联跳转
- ✅ OpenTelemetry 标准接入
- ✅ 服务拓扑图和依赖分析
4. 三大支柱联动
- ✅ Metrics → Logs：从指标异常跳转到相关日志
- ✅ Logs → Traces：从日志中的 trace_id 跳转到完整调用链
- ✅ Traces → Logs：从 trace span 跳转到该时间段的日志
- ✅ 统一 Grafana 界面查看
🔧 应用接入指南
接入日志（自动完成 ✅）
Promtail 作为 DaemonSet 自动采集所有 pod 的 stdout/stderr，无需修改应用代码。
推荐日志格式（JSON）：
{
"timestamp": "2025-12-16T08:00:00Z",
"level": "INFO",
"message": "Request processed successfully",
"trace_id": "abc123def456...",
"span_id": "789xyz...",
"service": "api-service",
"method": "GET",
"path": "/api/users",
"duration_ms": 123
}
接入链路追踪（需要代码修改）
OpenTelemetry 接入端点
OTLP gRPC: otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317
OTLP HTTP: otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318
Python (FastAPI) 示例
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
# 配置 OTLP exporter
otlp_exporter = OTLPSpanExporter(
endpoint="otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317",
insecure=True
)
# 设置 tracer provider
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
trace.set_tracer_provider(provider)
# 自动 instrument FastAPI
app = FastAPI()
FastAPIInstrumentor.instrument_app(app)
Spring Boot 配置
# application.yml
management:
otlp:
tracing:
endpoint: http://otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318/v1/traces
tracing:
sampling:
probability: 1.0 # 100% 采样（生产环境建议降低）
<!-- pom.xml -->
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-spring-boot-starter</artifactId>
<version>2.9.0</version>
</dependency>
⚠️ 告警规则
已配置 15+ 条告警规则，涵盖：
Node 级别（5 条）
- NodeDiskSpaceWarning/Critical - 磁盘空间不足
- NodeInodeSpaceWarning - inode 不足
- NodeMemoryPressure - 内存压力
- NodeCPUHigh - CPU 使用率过高
Pod 级别（4 条）
- PodCrashLoopBackOff - Pod 频繁重启
- PodPendingTooLong - Pod 长时间 Pending
- PodMemoryHigh/PodCPUHigh - 资源使用过高
Workload 级别（4 条）
- DeploymentReplicasMismatch - 副本数不匹配
- StatefulSetReplicasMismatch - StatefulSet 副本不足
- DaemonSetNotScheduled - DaemonSet 未完全部署
- JobFailed - Job 执行失败
可观测性组件（2 条）
- PrometheusScrapeFailure - 采集失败
- LokiLogEntriesDropped - 日志丢失
📁 文件清单
k8s/
├── loki-values.yaml # Loki + Promtail 配置
├── tempo-values.yaml # Tempo 配置
├── otel-collector-values.yaml # OpenTelemetry Collector 配置
├── grafana-datasources-updated.yaml # Grafana 数据源配置
├── prometheus-alerts.yaml # Prometheus 告警规则
├── verify-observability.sh # 验证脚本（可执行）
├── OBSERVABILITY-README.md # 本文件
├── OBSERVABILITY-GUIDE.md # 详细使用指南
└── DEPLOYMENT-SUMMARY.md # 部署总结
🔍 故障排查
查看组件状态
# 运行验证脚本
./verify-observability.sh
# 手动检查
kubectl get pods -n monitoring
kubectl get pods -n logging
kubectl get pods -n tracing
Loki 无法查询日志
# 检查 Promtail 日志
kubectl logs -n logging -l app.kubernetes.io/name=promtail --tail=50
# 检查 Loki 健康状态
kubectl exec -n logging loki-0 -- wget -q -O- http://localhost:3100/ready
# 查看已采集的标签
kubectl exec -n logging loki-0 -- wget -q -O- 'http://localhost:3100/loki/api/v1/labels'
Tempo 无法查询 traces
# 检查 OTel Collector 日志
kubectl logs -n tracing -l app.kubernetes.io/name=opentelemetry-collector --tail=50
# 检查 Tempo 日志
kubectl logs -n tracing tempo-0 --tail=50
# 验证应用是否正确发送 traces
kubectl logs <your-app-pod> | grep -i trace
Grafana 数据源连接失败
# 重启 Grafana
kubectl rollout restart deployment grafana -n monitoring
# 测试网络连通性
kubectl exec -n monitoring deployment/grafana -- wget -q -O- http://loki.logging.svc.cluster.local:3100/ready
kubectl exec -n monitoring deployment/grafana -- wget -q -O- http://tempo.tracing.svc.cluster.local:3200/ready
📚 学习资源
- OBSERVABILITY-GUIDE.md - 完整的使用指南和最佳实践
- DEPLOYMENT-SUMMARY.md - 部署总结和快速参考
- Prometheus 官方文档
- Loki 官方文档
- Tempo 官方文档
- OpenTelemetry 文档
🎯 下一步
- ✅ 导入推荐的 Grafana 仪表盘
- ✅ 在 Grafana Explore 中测试日志查询
- ✅ 配置应用接入链路追踪（参考 OBSERVABILITY-GUIDE.md）
- ✅ 配置 Alertmanager 通知渠道（邮件、Slack、Webhook）
- ✅ 根据业务需求添加自定义告警规则
- ✅ 定期备份 PVC 数据（loki、tempo）
📊 监控覆盖范围
| 类别 | 覆盖率 | 说明 |
|---|---|---|
| Metrics | 100% | 所有节点、Pod、Workload 自动监控 |
| Logs | 100% | Promtail DaemonSet 自动采集所有 pod 日志 |
| Traces | 按需 | 需要应用代码接入 OpenTelemetry |
| Alerts | 15+ 条 | 涵盖基础设施和应用层面 |
💡 最佳实践
日志最佳实践
- ✅ 使用结构化日志（JSON 格式）
- ✅ 包含 trace_id 和 span_id（实现 logs ↔ traces 关联）
- ✅ 使用统一的日志级别（DEBUG、INFO、WARN、ERROR、FATAL）
- ✅ 避免打印敏感信息（密码、token、身份证号等）
链路追踪最佳实践
- ✅ 使用 OpenTelemetry 标准（避免厂商锁定）
- ✅ 生产环境使用采样（10%-20% 采样率）
- ✅ 为 span 添加有意义的属性（http.method、http.status_code 等）
- ✅ 传播 trace context（确保跨服务调用链路完整）
监控最佳实践
- ✅ 使用 RED 方法（Rate、Errors、Duration）监控服务
- ✅ 使用 USE 方法（Utilization、Saturation、Errors）监控资源
- ✅ 设置合理的告警阈值（避免告警疲劳）
- ✅ 为每个告警配置 runbook（处理手册）
🔐 安全考虑
- ⚠️ 默认 Grafana 凭据（admin/admin）仅用于测试，生产环境必须修改
- ⚠️ 考虑启用 HTTPS（使用 Ingress + TLS）
- ⚠️ 配置 RBAC 限制数据访问权限
- ⚠️ 日志中避免包含敏感信息
- ⚠️ 定期更新组件版本（安全补丁）
部署日期: 2025-12-16 环境: OrbStack Kubernetes v1.33.5 部署工具: Helm 4.0.0 + kubectl 状态: ✅ 生产就绪 维护者: Bruno Gao