SuperBizAgent-java/docs/guides/日志配置与分析指南.md

日志配置与分析指南

配置日期：2026-05-30
配置目标：让 Claude 能够分析项目运行日志

---

📂 日志文件位置

项目启动后，日志文件会自动生成在 logs/ 目录：

logs/
├── application.log              # 所有日志（滚动存储）
├── application-error.log        # 仅 ERROR 级别日志
├── aiops.log                    # AI Ops 专用日志
├── chat.log                     # Chat 对话日志
├── application-2026-05-30.0.log # 按日期滚动的历史日志
└── ...

日志保留策略：

• 单个文件最大 10MB，超过后自动滚动
• 保留 30 天历史日志（application.log）
• 保留 15 天历史日志（aiops.log、chat.log）
• 所有日志总大小上限 1GB

---

🔧 配置详情

方式 1：application.yml 配置（已添加）

logging:
  file:
    name: logs/application.log
  level:
    root: INFO
    org.example: DEBUG  # 本项目日志级别
    org.springframework.ai: DEBUG  # Spring AI 日志

方式 2：logback-spring.xml 配置（已添加）

位置：src/main/resources/logback-spring.xml

特性：

• ✅ 控制台输出（彩色高亮）
• ✅ 文件输出（application.log）
• ✅ 错误日志单独文件（application-error.log）
• ✅ AI Ops 专用日志（aiops.log）
• ✅ Chat 专用日志（chat.log）
• ✅ 异步写入（性能优化）
• ✅ 按日期 + 大小滚动
• ✅ 第三方库降噪（WARN 级别）

---

🔍 如何让 Claude 分析日志

1. 查看实时日志

场景：分析正在运行的应用行为

# 查看最新 50 行日志
tail -n 50 logs/application.log

# 实时追踪日志（适合调试）
tail -f logs/application.log

# 只看 ERROR 日志
tail -f logs/application-error.log

# 只看 AI Ops 相关日志
tail -f logs/aiops.log

在 Claude Code 中使用：

! tail -n 100 logs/application.log

输出会直接进入对话，Claude 可以分析。

2. 搜索特定日志

场景：查找特定错误或关键词

# 搜索包含 "OOM" 的日志
grep "OOM" logs/application.log

# 搜索最近 1 小时的错误日志
grep "ERROR" logs/application.log | tail -n 100

# 搜索 AI Ops 相关的调用
grep "AiOpsService" logs/application.log

Claude Code 内置工具：

使用 Grep 工具搜索日志：
pattern: "ERROR.*OOM"
path: logs/application.log
output_mode: "content"

3. 分析日志片段

场景：重现 Bug 或分析性能问题

1. 重现问题（如触发 AI Ops）
2. 读取对应时间段的日志

   ! grep "2026-05-30 13:" logs/aiops.log
   

3. Claude 自动分析堆栈跟踪、错误信息、性能指标

---

📊 日志级别说明

级别	用途	示例
DEBUG	详细调试信息	ChatService 调用参数、AiOpsService 中间结果
INFO	关键业务流程	请求处理成功、模型切换、Milvus 连接
WARN	潜在问题	重试成功、配置缺失但有默认值
ERROR	错误需要关注	OOM、连接失败、模型调用失败

---

🎯 常见分析场景

场景 1：AI Ops 分析耗时

目标：分析哪个环节慢

! grep "AiOpsService" logs/aiops.log | tail -n 50

关注日志：

2026-05-30 13:00:00.123 [http-nio-9900-exec-1] DEBUG AiOpsService - 开始 AI Ops 分析
2026-05-30 13:00:01.456 [http-nio-9900-exec-1] DEBUG AiOpsService - Prometheus 告警查询完成，耗时 1233ms
2026-05-30 13:00:05.789 [http-nio-9900-exec-1] DEBUG AiOpsService - CLS 日志查询完成，耗时 4333ms
2026-05-30 13:00:56.123 [http-nio-9900-exec-1] DEBUG AiOpsService - LLM 推理完成，耗时 50334ms

场景 2：模型调用失败

目标：排查 DeepSeek 或 SiliconFlow 调用问题

! grep -E "ERROR.*(DeepSeek|SiliconFlow|ChatModel|EmbeddingModel)" logs/application-error.log

关注日志：

2026-05-30 13:00:00.123 [http-nio-9900-exec-1] ERROR ChatService - DeepSeek 调用失败
org.springframework.ai.retry.RetryException: 重试 3 次后仍失败
  at DeepSeekChatModel.call(...)
  Caused by: java.net.SocketTimeoutException: Read timed out

场景 3：Milvus 连接问题

目标：排查向量数据库问题

! grep -E "(MilvusClientFactory|VectorEmbeddingService)" logs/application.log | tail -n 50

关注日志：

2026-05-30 13:00:00.123 [main] INFO MilvusClientFactory - 连接 Milvus: in03-xxx.cloud.zilliz.com:443
2026-05-30 13:00:01.456 [main] INFO MilvusClientFactory - Collection 'biz' 已存在，跳过创建
2026-05-30 13:00:01.789 [main] INFO MilvusClientFactory - Collection 'biz' 加载到内存成功

场景 4：对话请求完整链路追踪

目标：从 HTTP 请求 → Chat 调用 → LLM 响应的完整链路

! grep -E "(ChatController|ChatService|DeepSeek)" logs/chat.log | tail -n 100

---

🛠️ Claude 分析日志的工作流

标准流程

1. 用户报告问题
   例如："AI Ops 分析很慢"

2. Claude 读取相关日志

   Read logs/aiops.log (limit: 100)
   

3. Claude 分析日志

   • 提取时间戳 → 计算耗时
   • 提取错误堆栈 → 定位问题代码行
   • 提取关键参数 → 理解上下文

4. Claude 给出结论
   "Prometheus 查询耗时 15s（正常 <1s），可能是 Prometheus 服务端慢查询，建议检查 PromQL 复杂度"

高级技巧

多文件关联分析：

Read logs/application.log (offset: 1000, limit: 50)  # 找到错误发生时间
Read logs/aiops.log  # 查看 AI Ops 当时在做什么
Read logs/chat.log   # 查看是否有并发请求

时间范围过滤：

Grep pattern="2026-05-30 13:0[0-5]" path="logs/application.log"  # 13:00-13:05 的日志

---

📝 日志最佳实践

开发时

// ✅ 好的日志
log.debug("AI Ops 分析开始，告警数量: {}", alerts.size());
log.info("Prometheus 查询完成，耗时: {}ms，结果数: {}", elapsed, results.size());
log.error("DeepSeek 调用失败，重试次数: {}", retryCount, exception);

// ❌ 差的日志
log.debug("开始");  // 没有上下文
log.info("完成");   // 没有结果
log.error("失败");  // 没有异常信息

关键业务流程必须记录

• AI Ops 分析：开始时间、告警数量、各环节耗时、LLM Token 消耗
• Chat 对话：请求 ID、模型名称、响应时间、是否流式
• RAG 检索：查询关键词、Top-K、相似度阈值、命中文档数
• 模型切换：从哪个模型切换到哪个模型、原因

---

🚀 快速启动与验证

1. 启动项目

mvn spring-boot:run

2. 验证日志文件生成

ls -lh logs/

应该看到：

application.log       # 立即生成
application-error.log # 有错误时生成
aiops.log            # 触发 AI Ops 后生成
chat.log             # 发送对话后生成

3. 测试日志输出

访问 http://localhost:9900，发送一条消息，然后：

! tail -n 20 logs/chat.log

应该看到 ChatService 的 DEBUG 日志。

---

🔗 相关文件

• 配置文件：src/main/resources/logback-spring.xml
• Spring Boot 配置：src/main/resources/application.yml（logging 部分）
• 忽略规则：.gitignore（logs/ 已忽略）

---

💡 提示：日志文件不会提交到 Git，只在本地存在。Claude 可以通过 Read/Grep 工具分析日志，帮助你调试问题。