Files

Roog (顾新培) 88cfe91c56 main:移除 src 目录结构，更新模块引用路径

变更内容：
- 删除 `src` 子目录，将模块引用路径从 `src.functional_scaffold` 更新为 `functional_scaffold`。
- 修改相关代码、文档、测试用例及配置文件中的路径引用，包括 `README.md`、`Dockerfile`、`uvicorn` 启动命令等。
- 优化项目目录结构，提升代码维护性和可读性。

2026-02-03 18:38:08 +08:00

4.7 KiB

Raw Blame History

Grafana 日志仪表板使用说明

Request ID 过滤功能

日志监控仪表板现在支持按 request_id 过滤日志，可以追踪单个请求的完整生命周期。

如何使用

访问仪表板
- 打开 Grafana: http://localhost:3000
- 登录（admin/admin）
- 进入 "日志监控" 仪表板
使用 Request ID 过滤
- 在仪表板顶部找到 "Request ID" 输入框
- 输入完整的 request_id（例如：59017bdd-5963-40b1-a325-5088593382c0）
- 所有面板会自动更新，只显示该 request_id 的日志
查看所有日志
- 清空 "Request ID" 输入框
- 所有面板会显示所有日志

示例

获取 Request ID

从 API 响应中获取：

curl -X POST http://localhost:8111/invoke \
  -H "Content-Type: application/json" \
  -d '{"number": 17}' | jq -r '.request_id'

输出示例：

59017bdd-5963-40b1-a325-5088593382c0

在仪表板中过滤

复制上面的 request_id
在 Grafana 仪表板顶部的 "Request ID" 输入框中粘贴
按回车或点击刷新

查看结果

过滤后，你会看到该请求的所有日志：

日志流面板：显示该请求的所有日志条目
日志量趋势：显示该请求的日志分布
日志级别分布：显示该请求的日志级别统计
错误日志：如果该请求有错误，会显示在这里

典型的请求日志流

一个成功的请求通常包含以下日志：

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 中使用

进入 Grafana Explore: http://localhost:3000/explore
选择 Loki 数据源
使用以下查询：

# 查询特定 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"

组合过滤

可以结合其他过滤条件：

# 特定 request_id 的 ERROR 日志
{job="functional-scaffold-app", level="ERROR"} |= "59017bdd-5963-40b1-a325-5088593382c0"

# 特定 request_id 的特定 logger
{job="functional-scaffold-app", logger="functional_scaffold.algorithms.base"} |= "59017bdd-5963-40b1-a325-5088593382c0"

故障排查

Request ID 过滤不生效

检查 request_id 格式
- 确保输入的是完整的 UUID 格式
- 不要包含额外的空格或引号
检查时间范围
- 确保仪表板的时间范围包含该请求的时间
- 可以调整为 "Last 15 minutes" 或更长
刷新仪表板
- 点击右上角的刷新按钮
- 或者按 Ctrl+R (Cmd+R on Mac)
验证日志是否存在
- 在 Explore 中手动查询：
```
{job="functional-scaffold-app"} |= "your-request-id"
```
- 如果没有结果，说明日志还没有被收集

日志延迟

Promtail 每 5 秒刷新一次
Loki 可能有几秒的延迟
建议等待 5-10 秒后再查询

最佳实践

调试单个请求
- 发送请求并记录 request_id
- 在仪表板中输入 request_id
- 查看完整的请求处理流程
追踪错误
- 当发现错误时，从错误日志中提取 request_id
- 使用 request_id 过滤查看完整的请求上下文
- 分析错误发生前后的日志
性能分析
- 使用 request_id 过滤慢请求
- 查看算法执行时间
- 分析性能瓶颈
用户问题排查
- 从用户报告中获取 request_id（如果有）
- 使用 request_id 重现问题场景
- 查看完整的请求处理过程

技术细节

过滤实现

仪表板使用 LogQL 的文本匹配操作符 |=：

{job="functional-scaffold-app"} |= "$request_id"

当 $request_id 为空时，|= "" 匹配所有日志
当 $request_id 有值时，只匹配包含该字符串的日志

性能考虑

文本匹配 (|=) 比 JSON 解析更快
适合实时查询和仪表板
对于精确匹配，可以在 Explore 中使用 JSON 解析

变量配置

Request ID 变量配置：

类型：textbox（文本输入框）
名称：request_id
标签：Request ID
默认值：空字符串

4.7 KiB Raw Blame History Unescape Escape