main:新增 Request ID 过滤文档及测试脚本
变更内容： - 编写《Grafana 日志仪表板使用说明》，详细介绍 Request ID 过滤功能及使用方法。 - 新增 `test_request_id_filter.sh` 脚本，用于验证 Request ID 过滤功能的正确性。 - 提升文档完备性，方便使用该功能进行日志调试和性能分析。
This commit is contained in:
182
docs/grafana-dashboard-usage.md
Normal file
182
docs/grafana-dashboard-usage.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Grafana 日志仪表板使用说明
|
||||
|
||||
## Request ID 过滤功能
|
||||
|
||||
日志监控仪表板现在支持按 request_id 过滤日志，可以追踪单个请求的完整生命周期。
|
||||
|
||||
### 如何使用
|
||||
|
||||
1. **访问仪表板**
|
||||
- 打开 Grafana: http://localhost:3000
|
||||
- 登录（admin/admin）
|
||||
- 进入 "日志监控" 仪表板
|
||||
|
||||
2. **使用 Request ID 过滤**
|
||||
- 在仪表板顶部找到 "Request ID" 输入框
|
||||
- 输入完整的 request_id（例如：`59017bdd-5963-40b1-a325-5088593382c0`）
|
||||
- 所有面板会自动更新，只显示该 request_id 的日志
|
||||
|
||||
3. **查看所有日志**
|
||||
- 清空 "Request ID" 输入框
|
||||
- 所有面板会显示所有日志
|
||||
|
||||
### 示例
|
||||
|
||||
#### 获取 Request ID
|
||||
|
||||
从 API 响应中获取：
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8111/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"number": 17}' | jq -r '.request_id'
|
||||
```
|
||||
|
||||
输出示例：
|
||||
```
|
||||
59017bdd-5963-40b1-a325-5088593382c0
|
||||
```
|
||||
|
||||
#### 在仪表板中过滤
|
||||
|
||||
1. 复制上面的 request_id
|
||||
2. 在 Grafana 仪表板顶部的 "Request ID" 输入框中粘贴
|
||||
3. 按回车或点击刷新
|
||||
|
||||
#### 查看结果
|
||||
|
||||
过滤后，你会看到该请求的所有日志：
|
||||
|
||||
- **日志流面板**：显示该请求的所有日志条目
|
||||
- **日志量趋势**：显示该请求的日志分布
|
||||
- **日志级别分布**：显示该请求的日志级别统计
|
||||
- **错误日志**：如果该请求有错误，会显示在这里
|
||||
|
||||
### 典型的请求日志流
|
||||
|
||||
一个成功的请求通常包含以下日志：
|
||||
|
||||
```
|
||||
1. Request: POST /invoke
|
||||
2. Processing request {request_id} with number=17
|
||||
3. Starting algorithm: PrimeChecker
|
||||
4. Algorithm PrimeChecker completed successfully in 0.001s
|
||||
5. Response: 200
|
||||
```
|
||||
|
||||
所有这些日志都有相同的 request_id，可以通过过滤功能一起查看。
|
||||
|
||||
### 高级用法
|
||||
|
||||
#### 在 Explore 中使用
|
||||
|
||||
1. 进入 Grafana Explore: http://localhost:3000/explore
|
||||
2. 选择 Loki 数据源
|
||||
3. 使用以下查询：
|
||||
|
||||
```logql
|
||||
# 查询特定 request_id
|
||||
{job="functional-scaffold-app"} |= "59017bdd-5963-40b1-a325-5088593382c0"
|
||||
|
||||
# 使用 JSON 解析（更精确）
|
||||
{job="functional-scaffold-app"} | json | request_id="59017bdd-5963-40b1-a325-5088593382c0"
|
||||
|
||||
# 查询特定 request_id 的错误日志
|
||||
{job="functional-scaffold-app", level="ERROR"} |= "59017bdd-5963-40b1-a325-5088593382c0"
|
||||
```
|
||||
|
||||
#### 组合过滤
|
||||
|
||||
可以结合其他过滤条件：
|
||||
|
||||
```logql
|
||||
# 特定 request_id 的 ERROR 日志
|
||||
{job="functional-scaffold-app", level="ERROR"} |= "59017bdd-5963-40b1-a325-5088593382c0"
|
||||
|
||||
# 特定 request_id 的特定 logger
|
||||
{job="functional-scaffold-app", logger="src.functional_scaffold.algorithms.base"} |= "59017bdd-5963-40b1-a325-5088593382c0"
|
||||
```
|
||||
|
||||
### 故障排查
|
||||
|
||||
#### Request ID 过滤不生效
|
||||
|
||||
1. **检查 request_id 格式**
|
||||
- 确保输入的是完整的 UUID 格式
|
||||
- 不要包含额外的空格或引号
|
||||
|
||||
2. **检查时间范围**
|
||||
- 确保仪表板的时间范围包含该请求的时间
|
||||
- 可以调整为 "Last 15 minutes" 或更长
|
||||
|
||||
3. **刷新仪表板**
|
||||
- 点击右上角的刷新按钮
|
||||
- 或者按 Ctrl+R (Cmd+R on Mac)
|
||||
|
||||
4. **验证日志是否存在**
|
||||
- 在 Explore 中手动查询：
|
||||
```logql
|
||||
{job="functional-scaffold-app"} |= "your-request-id"
|
||||
```
|
||||
- 如果没有结果，说明日志还没有被收集
|
||||
|
||||
#### 日志延迟
|
||||
|
||||
- Promtail 每 5 秒刷新一次
|
||||
- Loki 可能有几秒的延迟
|
||||
- 建议等待 5-10 秒后再查询
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **调试单个请求**
|
||||
- 发送请求并记录 request_id
|
||||
- 在仪表板中输入 request_id
|
||||
- 查看完整的请求处理流程
|
||||
|
||||
2. **追踪错误**
|
||||
- 当发现错误时，从错误日志中提取 request_id
|
||||
- 使用 request_id 过滤查看完整的请求上下文
|
||||
- 分析错误发生前后的日志
|
||||
|
||||
3. **性能分析**
|
||||
- 使用 request_id 过滤慢请求
|
||||
- 查看算法执行时间
|
||||
- 分析性能瓶颈
|
||||
|
||||
4. **用户问题排查**
|
||||
- 从用户报告中获取 request_id（如果有）
|
||||
- 使用 request_id 重现问题场景
|
||||
- 查看完整的请求处理过程
|
||||
|
||||
### 技术细节
|
||||
|
||||
#### 过滤实现
|
||||
|
||||
仪表板使用 LogQL 的文本匹配操作符 `|=`：
|
||||
|
||||
```logql
|
||||
{job="functional-scaffold-app"} |= "$request_id"
|
||||
```
|
||||
|
||||
- 当 `$request_id` 为空时，`|= ""` 匹配所有日志
|
||||
- 当 `$request_id` 有值时，只匹配包含该字符串的日志
|
||||
|
||||
#### 性能考虑
|
||||
|
||||
- 文本匹配 (`|=`) 比 JSON 解析更快
|
||||
- 适合实时查询和仪表板
|
||||
- 对于精确匹配，可以在 Explore 中使用 JSON 解析
|
||||
|
||||
#### 变量配置
|
||||
|
||||
Request ID 变量配置：
|
||||
- 类型：textbox（文本输入框）
|
||||
- 名称：request_id
|
||||
- 标签：Request ID
|
||||
- 默认值：空字符串
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Loki 集成文档](loki-integration.md)
|
||||
- [Loki 快速参考](loki-quick-reference.md)
|
||||
- [LogQL 查询语言](https://grafana.com/docs/loki/latest/logql/)
|
||||
Reference in New Issue
Block a user