FunctionalScaffold/docs/grafana-dashboard-guide.md

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 中没有数据或数据很少，运行流量生成脚本：

# 启动流量生成器
./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. 发送一些测试请求：

   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 请求速率

sum(rate(http_requests_total[1m])) by (endpoint, method)

HTTP 请求延迟 P95

histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[1m])) by (le, endpoint, method))

请求成功率

sum(rate(http_requests_total{status="success"}[5m])) / sum(rate(http_requests_total[5m]))

算法执行速率

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