main:添加核心文件并初始化项目
新增内容： - 创建基础项目结构。 - 添加 `.gitignore` 和 `.dockerignore` 文件。 - 编写 `pyproject.toml` 和依赖文件。 - 添加算法模块及示例算法。 - 实现核心功能模块（日志、错误处理、指标）。 - 添加开发和运行所需的相关脚本文件及文档。
This commit is contained in:
237
docs/grafana-dashboard-guide.md
Normal file
237
docs/grafana-dashboard-guide.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Grafana Dashboard 导入和使用指南
|
||||
|
||||
## Dashboard 概述
|
||||
|
||||
新的 dashboard 包含 10 个面板，全面展示应用的监控指标：
|
||||
|
||||
### 第一行：核心性能指标
|
||||
1. **HTTP 请求速率 (QPS)** - 每秒请求数，按端点和方法分组
|
||||
2. **HTTP 请求延迟 (P50/P95/P99)** - 请求响应时间的百分位数
|
||||
|
||||
### 第二行：关键指标
|
||||
3. **请求成功率** - 成功请求占比（仪表盘）
|
||||
4. **当前并发请求数** - 实时并发数（仪表盘）
|
||||
5. **HTTP 请求总数** - 累计请求数（统计卡片）
|
||||
6. **算法执行总数** - 累计算法调用数（统计卡片）
|
||||
|
||||
### 第三行：算法性能
|
||||
7. **算法执行速率** - 每秒算法执行次数
|
||||
8. **算法执行延迟 (P50/P95/P99)** - 算法执行时间的百分位数
|
||||
|
||||
### 第四行：分布分析
|
||||
9. **请求分布（按端点）** - 饼图展示各端点的请求占比
|
||||
10. **请求状态分布** - 饼图展示成功/失败请求占比
|
||||
|
||||
## 导入步骤
|
||||
|
||||
### 1. 配置 Prometheus 数据源
|
||||
|
||||
首先确保 Prometheus 数据源已正确配置：
|
||||
|
||||
1. 打开 Grafana：http://localhost:3000
|
||||
2. 登录（默认：admin/admin）
|
||||
3. 进入 **Configuration** → **Data Sources**
|
||||
4. 点击 **Add data source**
|
||||
5. 选择 **Prometheus**
|
||||
6. 配置：
|
||||
- **Name**: `Prometheus`（必须是这个名称）
|
||||
- **URL**: `http://prometheus:9090`（注意：使用服务名，不是 localhost）
|
||||
- **Access**: Server (default)
|
||||
7. 点击 **Save & Test**，确保显示绿色的成功提示
|
||||
|
||||
### 2. 导入 Dashboard
|
||||
|
||||
有两种方式导入 dashboard：
|
||||
|
||||
#### 方式 1：通过 JSON 文件导入（推荐）
|
||||
|
||||
1. 在 Grafana 左侧菜单，点击 **Dashboards** → **Import**
|
||||
2. 点击 **Upload JSON file**
|
||||
3. 选择文件：`monitoring/grafana/dashboard.json`
|
||||
4. 在导入页面：
|
||||
- **Name**: FunctionalScaffold 监控仪表板
|
||||
- **Folder**: General（或创建新文件夹）
|
||||
- **Prometheus**: 选择刚才配置的 Prometheus 数据源
|
||||
5. 点击 **Import**
|
||||
|
||||
#### 方式 2：通过 JSON 内容导入
|
||||
|
||||
1. 在 Grafana 左侧菜单，点击 **Dashboards** → **Import**
|
||||
2. 复制 `monitoring/grafana/dashboard.json` 的全部内容
|
||||
3. 粘贴到 **Import via panel json** 文本框
|
||||
4. 点击 **Load**
|
||||
5. 配置数据源并点击 **Import**
|
||||
|
||||
### 3. 验证 Dashboard
|
||||
|
||||
导入成功后，你应该看到：
|
||||
|
||||
- ✅ 所有面板都正常显示
|
||||
- ✅ 有数据的面板显示图表和数值
|
||||
- ✅ 右上角显示自动刷新（5秒）
|
||||
- ✅ 时间范围默认为最近 1 小时
|
||||
|
||||
## 生成测试数据
|
||||
|
||||
如果 dashboard 中没有数据或数据很少，运行流量生成脚本：
|
||||
|
||||
```bash
|
||||
# 启动流量生成器
|
||||
./scripts/generate_traffic.sh
|
||||
```
|
||||
|
||||
这会持续发送请求到应用，生成监控数据。等待 1-2 分钟后，dashboard 中应该会显示丰富的图表。
|
||||
|
||||
## Dashboard 功能
|
||||
|
||||
### 自动刷新
|
||||
|
||||
Dashboard 配置了自动刷新，默认每 5 秒更新一次。你可以在右上角修改刷新间隔：
|
||||
- 5s（默认）
|
||||
- 10s
|
||||
- 30s
|
||||
- 1m
|
||||
- 5m
|
||||
|
||||
### 时间范围
|
||||
|
||||
默认显示最近 1 小时的数据。你可以在右上角修改时间范围：
|
||||
- Last 5 minutes
|
||||
- Last 15 minutes
|
||||
- Last 30 minutes
|
||||
- Last 1 hour（默认）
|
||||
- Last 3 hours
|
||||
- Last 6 hours
|
||||
- Last 12 hours
|
||||
- Last 24 hours
|
||||
- 或自定义时间范围
|
||||
|
||||
### 实时模式
|
||||
|
||||
Dashboard 启用了 **Live** 模式（右上角的 Live 按钮），可以实时查看最新数据。
|
||||
|
||||
### 交互功能
|
||||
|
||||
- **缩放**：在时间序列图表上拖动选择区域可以放大
|
||||
- **图例点击**：点击图例可以隐藏/显示对应的数据系列
|
||||
- **Tooltip**：鼠标悬停在图表上查看详细数值
|
||||
- **面板全屏**：点击面板标题旁的图标可以全屏查看
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 问题 1：数据源连接失败
|
||||
|
||||
**错误信息**：`dial tcp [::1]:9090: connect: connection refused`
|
||||
|
||||
**解决方案**：
|
||||
- 确保 Prometheus URL 使用 `http://prometheus:9090`（服务名）
|
||||
- 不要使用 `http://localhost:9090`（在容器内部无法访问）
|
||||
|
||||
### 问题 2：面板显示 "No data"
|
||||
|
||||
**可能原因**：
|
||||
1. 应用还没有收到任何请求
|
||||
2. Prometheus 还没有抓取到数据
|
||||
3. 时间范围选择不当
|
||||
|
||||
**解决方案**：
|
||||
1. 发送一些测试请求：
|
||||
```bash
|
||||
curl -X POST http://localhost:8111/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"number": 17}'
|
||||
```
|
||||
2. 等待 15-30 秒让 Prometheus 抓取数据
|
||||
3. 调整时间范围为 "Last 5 minutes"
|
||||
4. 运行流量生成脚本：`./scripts/generate_traffic.sh`
|
||||
|
||||
### 问题 3：延迟图表显示 "NaN" 或空值
|
||||
|
||||
**原因**：直方图数据不足，无法计算百分位数
|
||||
|
||||
**解决方案**：
|
||||
- 发送更多请求以积累足够的数据
|
||||
- 等待几分钟让数据积累
|
||||
- 使用流量生成脚本持续发送请求
|
||||
|
||||
### 问题 4：数据源变量未正确设置
|
||||
|
||||
**错误信息**：面板显示 "Datasource not found"
|
||||
|
||||
**解决方案**：
|
||||
1. 确保 Prometheus 数据源的名称是 `Prometheus`
|
||||
2. 或者在 dashboard 设置中重新选择数据源：
|
||||
- 点击右上角的齿轮图标（Dashboard settings）
|
||||
- 进入 **Variables** 标签
|
||||
- 编辑 `DS_PROMETHEUS` 变量
|
||||
- 选择正确的 Prometheus 数据源
|
||||
|
||||
## PromQL 查询说明
|
||||
|
||||
Dashboard 使用的主要 PromQL 查询：
|
||||
|
||||
### HTTP 请求速率
|
||||
```promql
|
||||
sum(rate(http_requests_total[1m])) by (endpoint, method)
|
||||
```
|
||||
|
||||
### HTTP 请求延迟 P95
|
||||
```promql
|
||||
histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[1m])) by (le, endpoint, method))
|
||||
```
|
||||
|
||||
### 请求成功率
|
||||
```promql
|
||||
sum(rate(http_requests_total{status="success"}[5m])) / sum(rate(http_requests_total[5m]))
|
||||
```
|
||||
|
||||
### 算法执行速率
|
||||
```promql
|
||||
sum(rate(algorithm_executions_total[1m])) by (algorithm, status)
|
||||
```
|
||||
|
||||
## 自定义 Dashboard
|
||||
|
||||
你可以根据需要自定义 dashboard：
|
||||
|
||||
1. **添加新面板**：点击右上角的 "Add panel" 按钮
|
||||
2. **编辑面板**：点击面板标题 → Edit
|
||||
3. **调整布局**：拖动面板调整位置和大小
|
||||
4. **保存更改**：点击右上角的保存图标
|
||||
|
||||
## 导出和分享
|
||||
|
||||
### 导出 Dashboard
|
||||
|
||||
1. 点击右上角的分享图标
|
||||
2. 选择 **Export** 标签
|
||||
3. 点击 **Save to file** 下载 JSON 文件
|
||||
|
||||
### 分享 Dashboard
|
||||
|
||||
1. 点击右上角的分享图标
|
||||
2. 选择 **Link** 标签
|
||||
3. 复制链接分享给团队成员
|
||||
|
||||
## 告警配置（可选）
|
||||
|
||||
你可以为面板配置告警规则：
|
||||
|
||||
1. 编辑面板
|
||||
2. 切换到 **Alert** 标签
|
||||
3. 点击 **Create alert rule from this panel**
|
||||
4. 配置告警条件和通知渠道
|
||||
|
||||
## 相关资源
|
||||
|
||||
- Grafana 官方文档：https://grafana.com/docs/
|
||||
- Prometheus 查询语言：https://prometheus.io/docs/prometheus/latest/querying/basics/
|
||||
- Dashboard 最佳实践：https://grafana.com/docs/grafana/latest/best-practices/
|
||||
|
||||
## 技术支持
|
||||
|
||||
如果遇到问题：
|
||||
1. 检查 Prometheus 是否正常运行：http://localhost:9090
|
||||
2. 检查应用 metrics 端点：http://localhost:8111/metrics
|
||||
3. 查看 Grafana 日志：`docker-compose logs grafana`
|
||||
4. 查看 Prometheus 日志：`docker-compose logs prometheus`
|
||||
Reference in New Issue
Block a user