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