# 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. 验证部署状态
```bash
./verify-observability.sh
```

### 2. 访问 Grafana
```bash
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）
```logql
# 查看所有日志
{namespace=~".+"}

# 查看特定应用日志
{namespace="fastapi", pod=~".*"}

# 查看错误日志
{namespace="fastapi"} |= "ERROR"

# 从日志跳转到 trace（如果日志包含 trace_id）
{namespace="fastapi"} | json | trace_id != ""
```

### 5. 访问 Prometheus
```bash
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）**：
```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) 示例
```python
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 配置
```yaml
# application.yml
management:
  otlp:
    tracing:
      endpoint: http://otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318/v1/traces
  tracing:
    sampling:
      probability: 1.0  # 100% 采样（生产环境建议降低）
```

```xml
<!-- 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               # 部署总结
```

## 🔍 故障排查

### 查看组件状态
```bash
# 运行验证脚本
./verify-observability.sh

# 手动检查
kubectl get pods -n monitoring
kubectl get pods -n logging
kubectl get pods -n tracing
```

### Loki 无法查询日志
```bash
# 检查 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
```bash
# 检查 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 数据源连接失败
```bash
# 重启 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 官方文档](https://prometheus.io/docs/)
- [Loki 官方文档](https://grafana.com/docs/loki/latest/)
- [Tempo 官方文档](https://grafana.com/docs/tempo/latest/)
- [OpenTelemetry 文档](https://opentelemetry.io/docs/)

## 🎯 下一步

1. ✅ 导入推荐的 Grafana 仪表盘
2. ✅ 在 Grafana Explore 中测试日志查询
3. ✅ 配置应用接入链路追踪（参考 OBSERVABILITY-GUIDE.md）
4. ✅ 配置 Alertmanager 通知渠道（邮件、Slack、Webhook）
5. ✅ 根据业务需求添加自定义告警规则
6. ✅ 定期备份 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