tokens-reef/deploy/monitoring

Sub2API 监控栈

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

架构概览

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

快速开始

1. 准备工作

cd deploy/monitoring

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

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

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

2. 启动监控栈

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 指标：

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 查询示例

# 当前可用性
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 日志查询示例

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

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

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

故障排查

检查服务状态

# 查看所有服务状态
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 配置：

   curl -X POST http://localhost:9090/-/reload
   

集成外部服务

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

维护操作

备份数据

# 备份 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/

清理旧数据

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

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

升级组件

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

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

参考文档

• Prometheus 文档
• Grafana 文档
• Loki 文档
• Jaeger 文档
• Alertmanager 文档

支持

如有问题，请联系：

• SRE Team: sre@sub2api.org
• On-Call: oncall@sub2api.org