tokens-reef/deploy/monitoring/README.md

# Sub2API 监控栈

基于 Prometheus + Grafana + Loki + Jaeger 的完整可观测性解决方案。

## 架构概览

```
┌─────────────────────────────────────────────────────────────────┐
│                        监控栈架构                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ Prometheus  │  │    Loki     │  │   Jaeger    │             │
│  │  (指标存储)  │  │  (日志存储)  │  │  (追踪存储)  │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          ▼                                      │
│                   ┌─────────────┐                              │
│                   │   Grafana   │                              │
│                   │  (可视化)    │                              │
│                   └─────────────┘                              │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  Promtail   │  │ Node Exp    │  │  cAdvisor   │             │
│  │ (日志收集)   │  │ (主机指标)   │  │ (容器指标)   │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## 快速开始

### 1. 准备工作

```bash
cd deploy/monitoring

# 创建数据目录
mkdir -p prometheus-data grafana-data loki-data alertmanager-data

# 复制环境变量配置
cp .env.example .env

# 编辑 .env 文件，配置你的告警通知方式
vim .env
```

### 2. 启动监控栈

```bash
docker-compose -f docker-compose.monitoring.yml up -d
```

### 3. 访问服务

| 服务 | URL | 默认账号 |
|------|-----|----------|
| Grafana | http://localhost:3000 | admin/admin |
| Prometheus | http://localhost:9090 | - |
| Jaeger UI | http://localhost:16686 | - |
| Alertmanager | http://localhost:9093 | - |

### 4. 配置 Sub2API 应用指标暴露

在 Sub2API 后端代码中集成 Prometheus 指标：

```go
import (
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

// 在路由中添加 metrics 端点
router.GET("/metrics", gin.WrapH(promhttp.Handler()))
```

### 5. 查看 Dashboard

1. 登录 Grafana (http://localhost:3000)
2. 导航到 Dashboards -> Sub2API
3. 查看以下预设 Dashboard：
   - **系统概览** - 整体健康度和关键指标
   - **SLO 监控** - 服务水平目标达成情况
   - **网关性能** - API 网关详细性能指标
   - **上游健康** - 上游 AI 服务状态

## 配置说明

### Prometheus 配置

配置文件：`prometheus/prometheus.yml`

主要配置项：
- 抓取目标（Sub2API、Node Exporter、cAdvisor）
- 告警规则路径
- Alertmanager 地址
- 数据保留策略

### 告警规则

配置文件：`prometheus/rules/sub2api-alerts.yml`

预设告警：
- **SLO 告警** - 基于错误预算燃烧率的多窗口告警
- **延迟告警** - P99/P95 延迟阈值告警
- **错误率告警** - HTTP 5xx 错误率告警
- **基础设施告警** - CPU、内存、磁盘、连接池
- **业务告警** - QPS、账号切换频率

### Alertmanager 配置

配置文件：`alertmanager/config.yml`

支持的通知渠道：
- Email
- Slack
- PagerDuty
- Webhook

### Grafana 配置

- **数据源**：Prometheus、Loki、Jaeger
- **Dashboard**：系统概览、SLO 监控、错误分析
- **告警**：可视化告警配置

### Loki 日志配置

配置文件：`loki/loki-config.yaml`

- 日志收集：Promtail 从 Docker 容器和文件收集
- 日志查询：Grafana Explore 中查询日志
- 日志告警：基于日志内容的告警

## 常用查询

### Prometheus 查询示例

```promql
# 当前可用性
1 - (sum(rate(sub2api_http_requests_total{status=~"5.."}[5m])) / sum(rate(sub2api_http_requests_total[5m])))

# P99 延迟
histogram_quantile(0.99, sum(rate(sub2api_http_request_duration_seconds_bucket[5m])) by (le))

# QPS
sum(rate(sub2api_http_requests_total[1m]))

# 错误预算燃烧率
(sum(rate(sub2api_http_requests_total{status=~"5.."}[1h])) / sum(rate(sub2api_http_requests_total[1h]))) / 0.0005
```

### Loki 日志查询示例

```logql
# 查看错误日志
{job="sub2api"} |= "error" | json

# 查看特定请求的日志
{job="sub2api"} |= "trace_id=\"xxx\""

# 按错误类型统计
sum by (error_type) (rate({job="sub2api"} |= "error" | json [5m]))
```

## 故障排查

### 检查服务状态

```bash
# 查看所有服务状态
docker-compose -f docker-compose.monitoring.yml ps

# 查看服务日志
docker-compose -f docker-compose.monitoring.yml logs -f prometheus
docker-compose -f docker-compose.monitoring.yml logs -f grafana
docker-compose -f docker-compose.monitoring.yml logs -f loki
```

### 常见问题

1. **Prometheus 无法抓取指标**
   - 检查 Sub2API `/metrics` 端点是否可访问
   - 检查网络连通性
   - 查看 Prometheus Targets 页面

2. **Grafana 无法显示数据**
   - 检查数据源配置
   - 验证 Prometheus 查询
   - 查看浏览器开发者工具

3. **告警不触发**
   - 检查告警规则语法
   - 验证 Alertmanager 配置
   - 查看 Alertmanager 状态页面

## 扩展配置

### 添加自定义 Dashboard

1. 在 Grafana 中创建 Dashboard
2. 导出 JSON 文件
3. 保存到 `grafana/dashboards/` 目录
4. 重启 Grafana 服务

### 添加自定义告警规则

1. 编辑 `prometheus/rules/sub2api-alerts.yml`
2. 添加新的告警规则
3. 重新加载 Prometheus 配置：
   ```bash
   curl -X POST http://localhost:9090/-/reload
   ```

### 集成外部服务

- **PagerDuty**: 配置 `PAGERDUTY_WEBHOOK_URL`
- **Slack**: 配置 `SLACK_WEBHOOK_URL`
- **自定义 Webhook**: 修改 `alertmanager/config.yml`

## 维护操作

### 备份数据

```bash
# 备份 Prometheus 数据
tar czf prometheus-backup-$(date +%Y%m%d).tar.gz prometheus-data/

# 备份 Grafana 配置
tar czf grafana-backup-$(date +%Y%m%d).tar.gz grafana-data/
```

### 清理旧数据

```bash
# Prometheus 数据清理 (保留30天)
curl -X POST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]={__name__=~".+"}'

# Loki 数据自动清理 (按配置保留)
```

### 升级组件

```bash
# 更新镜像版本
vim docker-compose.monitoring.yml

# 重新部署
docker-compose -f docker-compose.monitoring.yml pull
docker-compose -f docker-compose.monitoring.yml up -d
```

## 参考文档

- [Prometheus 文档](https://prometheus.io/docs/)
- [Grafana 文档](https://grafana.com/docs/)
- [Loki 文档](https://grafana.com/docs/loki/)
- [Jaeger 文档](https://www.jaegertracing.io/docs/)
- [Alertmanager 文档](https://prometheus.io/docs/alerting/latest/alertmanager/)

## 支持

如有问题，请联系：
- SRE Team: sre@sub2api.org
- On-Call: oncall@sub2api.org