# Kubernetes 可观测性栈部署总结

## ✅ 部署完成

### 已安装组件

#### 1. Metrics（指标监控）
- ✅ Prometheus - 指标存储和查询引擎
- ✅ Grafana - 可视化平台
- ✅ Alertmanager - 告警管理
- ✅ kube-state-metrics - Kubernetes 对象状态指标
- ✅ node-exporter - 节点级别系统指标

#### 2. Logs（日志系统）
- ✅ Loki - 日志聚合和存储（namespace: logging）
- ✅ Promtail - 日志采集 DaemonSet（自动采集所有 pod 日志）

#### 3. Traces（链路追踪）
- ✅ Tempo - 分布式追踪存储（namespace: tracing）
- ✅ OpenTelemetry Collector - 链路数据采集和转发

#### 4. 告警规则
- ✅ Node 级别告警（磁盘、内存、CPU、inode）
- ✅ Pod 级别告警（重启、Pending、资源使用）
- ✅ Workload 级别告警（Deployment、StatefulSet、DaemonSet、Job）
- ✅ 可观测性组件告警（Prometheus、Loki）

## 🔗 访问地址

| 组件 | 地址 | 凭据 |
|------|------|------|
| **Grafana** | http://localhost:30300 | admin/admin |
| **Prometheus** | http://localhost:30900 | - |

## 📊 Grafana 数据源配置

Grafana 已自动配置以下数据源：

1. **Prometheus** (默认数据源)
   - URL: `http://prometheus:9090`
   - 用于查询指标数据

2. **Loki**
   - URL: `http://loki.logging.svc.cluster.local:3100`
   - 用于查询日志数据
   - 支持从日志跳转到 Tempo traces

3. **Tempo**
   - URL: `http://tempo.tracing.svc.cluster.local:3200`
   - 用于查询分布式追踪数据
   - 支持从 trace 跳转到 Loki 日志

## 🚀 快速验证

### 1. 验证所有组件运行状态
```bash
# 查看 monitoring namespace
kubectl get pods -n monitoring

# 查看 logging namespace
kubectl get pods -n logging

# 查看 tracing namespace
kubectl get pods -n tracing
```

### 2. 验证 Grafana 数据源
```bash
# 访问 Grafana
open http://localhost:30300

# 登录后，进入 Configuration → Data sources
# 应该看到 3 个数据源：Prometheus, Loki, Tempo（全部为绿色 ✓）
```

### 3. 验证日志采集
在 Grafana Explore 中：
```logql
# 查看所有日志
{namespace=~".+"}

# 查看特定 namespace 的日志
{namespace="fastapi"}

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

### 4. 验证告警规则
```bash
# 访问 Prometheus
open http://localhost:30900

# 点击 "Status" → "Rules"
# 应该看到以下告警组：
# - node-alerts (5 rules)
# - pod-alerts (4 rules)
# - workload-alerts (4 rules)
# - observability-alerts (2 rules)
```

## 📈 推荐导入的 Grafana 仪表盘

访问 Grafana → Dashboards → New → Import，输入以下 ID：

### 必备仪表盘（优先导入）
1. **1860** - Node Exporter Full（节点监控）
2. **15758** - Kubernetes Views Pods（Pod 监控）
3. **13639** - Logs / App（应用日志）
4. **315** - Kubernetes cluster monitoring（集群监控）

### 可选仪表盘
5. **15757** - Kubernetes Views Namespaces
6. **15759** - Kubernetes Views Nodes
7. **12611** - Loki & Promtail
8. **16110** - Tempo / Operational

详细说明请参考：`OBSERVABILITY-GUIDE.md`

## 🔧 应用接入指南

### 接入日志（自动）
✅ **已自动完成** - Promtail DaemonSet 自动采集所有 pod 的 stdout/stderr

**推荐日志格式（JSON）**：
```json
{
  "timestamp": "2025-12-16T08:00:00Z",
  "level": "INFO",
  "message": "Request processed",
  "trace_id": "abc123...",
  "span_id": "def456...",
  "service": "api-service"
}
```

### 接入链路追踪（需要代码修改）

**OTLP 端点**：
- gRPC: `otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317`
- HTTP: `otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318`

**Python (FastAPI) 示例**：
```python
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

otlp_exporter = OTLPSpanExporter(
    endpoint="otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317",
    insecure=True
)
```

**Spring Boot 配置**：
```yaml
management:
  otlp:
    tracing:
      endpoint: http://otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318/v1/traces
```

详细接入指南请参考：`OBSERVABILITY-GUIDE.md`

## 📁 配置文件清单

| 文件 | 说明 |
|------|------|
| `loki-values.yaml` | Loki + Promtail 配置 |
| `tempo-values.yaml` | Tempo 配置 |
| `otel-collector-values.yaml` | OpenTelemetry Collector 配置 |
| `grafana-datasources-updated.yaml` | Grafana 数据源配置 |
| `prometheus-alerts.yaml` | Prometheus 告警规则 |
| `OBSERVABILITY-GUIDE.md` | 完整使用指南 |
| `DEPLOYMENT-SUMMARY.md` | 本文件 |

## 🔍 验证脚本

运行以下命令验证所有组件：

```bash
# 1. 检查所有 pods 状态
echo "=== Monitoring Namespace ==="
kubectl get pods -n monitoring

echo -e "\n=== Logging Namespace ==="
kubectl get pods -n logging

echo -e "\n=== Tracing Namespace ==="
kubectl get pods -n tracing

# 2. 检查所有 services
echo -e "\n=== Services ==="
kubectl get svc -n monitoring | grep -E "(grafana|prometheus|alertmanager)"
kubectl get svc -n logging
kubectl get svc -n tracing

# 3. 验证 Loki 健康状态
echo -e "\n=== Loki Health Check ==="
kubectl exec -n logging loki-0 -- wget -q -O- http://localhost:3100/ready

# 4. 验证 Tempo 是否正常
echo -e "\n=== Tempo Status ==="
kubectl get pods -n tracing -l app.kubernetes.io/name=tempo

# 5. 验证 OTel Collector 是否正常
echo -e "\n=== OTel Collector Status ==="
kubectl get pods -n tracing -l app.kubernetes.io/name=opentelemetry-collector

# 6. 检查告警规则
echo -e "\n=== Prometheus Rules ==="
kubectl get prometheusrule -n monitoring

echo -e "\n✅ 验证完成！"
echo "访问 Grafana: http://localhost:30300 (admin/admin)"
echo "访问 Prometheus: http://localhost:30900"
```

将上述脚本保存为 `verify-observability.sh`，然后运行：
```bash
chmod +x verify-observability.sh
./verify-observability.sh
```

## 🐛 故障排查

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

### Grafana 数据源连接失败
```bash
# 重启 Grafana
kubectl rollout restart deployment grafana -n monitoring

# 检查 Grafana 日志
kubectl logs -n monitoring -l app.kubernetes.io/name=grafana --tail=50
```

## 📚 下一步

1. ✅ 导入推荐的 Grafana 仪表盘
2. ✅ 配置 Alertmanager 通知（邮件、Slack 等）
3. ✅ 应用接入链路追踪（修改应用代码）
4. ✅ 定期备份 PVC 数据
5. ✅ 根据业务需求添加自定义告警规则

## 🎓 学习资源

- [完整使用指南](./OBSERVABILITY-GUIDE.md)
- [Prometheus 查询语言](https://prometheus.io/docs/prometheus/latest/querying/basics/)
- [LogQL 查询语言](https://grafana.com/docs/loki/latest/query/)
- [OpenTelemetry 文档](https://opentelemetry.io/docs/)

---

**部署日期**: 2025-12-16
**环境**: OrbStack Kubernetes v1.33.5
**部署工具**: Helm + kubectl
**状态**: ✅ 生产就绪