# Kubernetes 可观测性完整指南

本指南介绍如何使用已部署的 Prometheus + Grafana + Loki + Tempo 完整可观测性栈。

## 🎯 已部署组件

### Metrics（指标）
- **Prometheus**: http://localhost:30900 - 指标存储和查询
- **Grafana**: http://localhost:30300 - 可视化和仪表盘（默认用户名/密码：admin/admin）
- **Alertmanager**: 告警管理
- **kube-state-metrics**: Kubernetes 对象状态指标
- **node-exporter**: 节点级别系统指标

### Logs（日志）
- **Loki**: 日志存储和查询（在 `logging` namespace）
- **Promtail**: 日志采集（DaemonSet，采集所有 pod 日志）

### Traces（链路追踪）
- **Tempo**: 链路存储和查询（在 `tracing` namespace）
- **OpenTelemetry Collector**: 链路数据采集和转发

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

访问 Grafana (http://localhost:30300)，点击左侧菜单 "Dashboards" → "New" → "Import"，输入以下 ID：

### 1. 节点监控（Node Exporter）
- **Dashboard ID: 1860** - Node Exporter Full
  - 完整的节点级别监控
  - CPU、内存、磁盘、网络、文件系统等

### 2. Kubernetes 集群监控
- **Dashboard ID: 15758** - Kubernetes Views Pods
  - Pod 级别的资源使用、重启、状态
  - 按 namespace 分组查看

- **Dashboard ID: 15757** - Kubernetes Views Namespaces
  - Namespace 级别的资源使用
  - CPU、内存、网络汇总

- **Dashboard ID: 15759** - Kubernetes Views Nodes
  - 节点级别的资源分配和使用
  - 容量规划视图

### 3. Kubernetes 详细监控
- **Dashboard ID: 315** - Kubernetes cluster monitoring
  - 集群整体健康状况
  - Pod、Deployment、StatefulSet 状态

- **Dashboard ID: 13770** - Kubernetes / Views / Global
  - 全局视图：所有资源的汇总

### 4. Loki 日志监控
- **Dashboard ID: 13639** - Logs / App
  - 应用日志查看和分析
  - 支持日志到 trace 的跳转

- **Dashboard ID: 12611** - Loki & Promtail
  - Loki 和 Promtail 自身的监控
  - 日志采集速率、存储使用

### 5. Tempo 链路追踪监控
- **Dashboard ID: 16110** - Tempo / Operational
  - Tempo 自身的运维监控
  - Trace 吞吐量、延迟分布

### 6. OpenTelemetry Collector 监控
- **Dashboard ID: 15983** - OpenTelemetry Collector
  - OTel Collector 的监控
  - 接收器、处理器、导出器指标

## 🔍 使用场景示例

### 场景 1: 查看应用日志
1. 访问 Grafana → Explore
2. 选择数据源：**Loki**
3. 使用查询：
   ```logql
   {namespace="fastapi", pod=~".*"}
   ```
4. 筛选特定级别日志：
   ```logql
   {namespace="fastapi"} |= "ERROR"
   ```

### 场景 2: 从日志跳转到 Trace
1. 在 Loki 日志中查找包含 `trace_id` 的日志
2. 点击 trace_id 链接，自动跳转到 Tempo
3. 在 Tempo 中查看完整的调用链路

### 场景 3: 从 Trace 跳转到日志
1. 在 Grafana → Explore 中选择 **Tempo**
2. 搜索 trace（通过 trace ID 或服务名）
3. 在 trace 详情页面，点击 span 上的 "Logs" 按钮
4. 自动跳转到该时间段的相关日志

### 场景 4: 监控 Pod 资源使用
1. 导入 Dashboard ID: 15758
2. 选择 namespace 和 pod
3. 查看 CPU、内存、网络、磁盘 I/O 等指标
4. 发现异常时，点击 "View Logs" 按钮查看日志

### 场景 5: 告警配置
1. 访问 Alertmanager（通过 Prometheus UI）
2. 查看已配置的告警规则
3. 告警触发时会显示在 Grafana 的 Alerting 页面

## 🔧 应用接入指南

### 接入日志（所有应用自动接入）
Promtail 作为 DaemonSet 运行在每个节点，自动采集所有 pod 的日志。

**最佳实践**：
```json
{
  "timestamp": "2025-12-16T08:00:00Z",
  "level": "INFO",
  "message": "Request processed successfully",
  "trace_id": "abc123...",
  "span_id": "def456...",
  "service": "api-service",
  "method": "GET",
  "path": "/api/users"
}
```

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

#### 方式 1: 使用 OTLP（推荐）
应用发送 traces 到：
```
otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4317  # gRPC
otel-collector-opentelemetry-collector.tracing.svc.cluster.local:4318  # HTTP
```

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

#### 方式 2: 使用 Jaeger SDK（向后兼容）
应用发送到：
```
otel-collector-opentelemetry-collector.tracing.svc.cluster.local:14250  # gRPC
otel-collector-opentelemetry-collector.tracing.svc.cluster.local:14268  # HTTP
```

## 📈 告警规则说明

已配置的告警规则（在 `prometheus-alerts.yaml`）：

### 节点级别
- **NodeDiskSpaceWarning**: 磁盘空间 < 20%
- **NodeDiskSpaceCritical**: 磁盘空间 < 10%
- **NodeInodeSpaceWarning**: inode < 20%
- **NodeMemoryPressure**: 内存使用 > 85%
- **NodeCPUHigh**: CPU 使用 > 80% 持续 10 分钟

### Pod 级别
- **PodCrashLoopBackOff**: Pod 频繁重启
- **PodPendingTooLong**: Pod Pending > 10 分钟
- **PodMemoryHigh**: 内存使用 > 限制的 90%
- **PodCPUHigh**: CPU 使用 > 限制的 90%

### Workload 级别
- **DeploymentReplicasMismatch**: Deployment 副本数不匹配
- **StatefulSetReplicasMismatch**: StatefulSet 副本数不匹配
- **DaemonSetNotScheduled**: DaemonSet 未完全部署
- **JobFailed**: Job 执行失败

### 可观测性组件
- **PrometheusScrapeFailure**: Prometheus 采集失败
- **LokiLogEntriesDropped**: Loki 日志丢失

## 🚀 应用告警规则

```bash
# 应用告警规则
kubectl apply -f prometheus-alerts.yaml

# 重启 Prometheus 以加载新规则（如果需要）
kubectl rollout restart deployment prometheus -n monitoring
```

## 🔗 关键链接

- **Grafana**: http://localhost:30300 (admin/admin)
- **Prometheus**: http://localhost:30900
- **Grafana 官方仪表盘库**: https://grafana.com/grafana/dashboards/

## 📚 进阶主题

### 1. 配置 Alertmanager 通知
编辑 Alertmanager 配置，添加邮件、Slack、Webhook 等通知渠道。

### 2. 自定义告警规则
在 `prometheus-alerts.yaml` 中添加业务相关的告警规则。

### 3. 优化 Loki 日志查询性能
- 使用 label 过滤而非正则表达式
- 限制查询时间范围
- 使用 `|= "string"` 而非 `|~ "regex"`

### 4. 优化 Tempo 采样率
生产环境建议降低采样率（如 10%）以减少存储开销：
```yaml
# 在应用配置中
sampling:
  probability: 0.1  # 10% 采样率
```

### 5. 持久化数据备份
确保定期备份 PVC：
- `loki` namespace 的 `storage-loki-0`
- `tracing` namespace 的 `storage-tempo-0`

## 🐛 故障排查

### Loki 无法查询日志
```bash
# 检查 Promtail 状态
kubectl get pods -n logging
kubectl logs -n logging -l app.kubernetes.io/name=promtail

# 检查 Loki 健康状态
kubectl exec -n logging loki-0 -- wget -q -O- http://localhost:3100/ready
```

### Tempo 无法显示 traces
```bash
# 检查 OTel Collector 状态
kubectl get pods -n tracing
kubectl logs -n tracing -l app.kubernetes.io/name=opentelemetry-collector

# 检查应用是否正确发送 traces
kubectl logs <your-app-pod> | grep -i trace
```

### Grafana 数据源连接失败
```bash
# 检查网络连通性
kubectl exec -n monitoring <grafana-pod> -- wget -q -O- http://loki.logging.svc.cluster.local:3100/ready
kubectl exec -n monitoring <grafana-pod> -- wget -q -O- http://tempo.tracing.svc.cluster.local:3200/ready
```

## 🎓 学习资源

- [Prometheus 查询语言 (PromQL)](https://prometheus.io/docs/prometheus/latest/querying/basics/)
- [LogQL (Loki 查询语言)](https://grafana.com/docs/loki/latest/query/)
- [OpenTelemetry 文档](https://opentelemetry.io/docs/)
- [Grafana 官方文档](https://grafana.com/docs/grafana/latest/)

---

**部署完成时间**: 2025-12-16
**维护者**: Claude Code
**版本**: v1.0