SuperBizAgent-java/docs/日志配置完成总结.md

日志配置完成总结

✅ 已完成的工作

1. 配置文件添加

文件	说明
src/main/resources/application.yml	添加 logging 配置（简单模式）
src/main/resources/logback-spring.xml	Logback 完整配置（推荐使用）

2. 日志输出位置

项目启动后，日志会自动输出到：

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

3. 日志特性

• ✅ 控制台输出 + 文件输出（双通道）
• ✅ 彩色高亮（控制台）
• ✅ 按模块分文件（aiops.log、chat.log）
• ✅ 异步写入（提升性能）
• ✅ 自动滚动（按日期 + 大小）
• ✅ 保留 30 天（可配置）
• ✅ 总大小限制 1GB（防止磁盘爆满）

4. 日志级别

包	级别	说明
org.example	DEBUG	本项目所有类（详细日志）
org.springframework.ai	DEBUG	Spring AI 框架
org.springframework	INFO	Spring 框架
com.alibaba.cloud	WARN	第三方库降噪
ROOT	INFO	其他所有

---

🚀 使用方式

方式 1：启动项目后手动查看

# 启动项目
mvn spring-boot:run

# 另一个终端查看日志
tail -f logs/application.log

# 只看错误
tail -f logs/application-error.log

# 只看 AI Ops
tail -f logs/aiops.log

方式 2：在 Claude Code 中分析（推荐）

实时日志：

! tail -n 100 logs/application.log

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

搜索日志：

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

读取日志片段：

Read logs/application.log (limit: 100)
Read logs/aiops.log (offset: 500, limit: 50)

---

📊 典型分析场景

场景 1：AI Ops 分析耗时诊断

1. 用户报告："AI Ops 分析太慢"
2. Claude 执行：Read logs/aiops.log (limit: 100)
3. Claude 分析：
   - Prometheus 查询 15s（异常，正常 <1s）
   - CLS 日志查询 4s（正常）
   - LLM 推理 35s（正常）
4. 结论：Prometheus 服务端慢查询，建议优化 PromQL

场景 2：模型调用失败排查

1. 用户报告："对话没有响应"
2. Claude 执行：Grep pattern="ERROR.*DeepSeek" path=logs/application-error.log
3. Claude 分析：
   java.net.SocketTimeoutException: Read timed out
   at DeepSeekChatModel.call(...)
4. 结论：DeepSeek API 超时，建议增加 timeout 或检查网络

场景 3：完整链路追踪

1. 用户报告："某次对话返回了错误结果"
2. Claude 执行：
   - Read logs/chat.log → 找到请求时间 13:05:23
   - Grep pattern="13:05:2[0-9]" path=logs/application.log → 完整链路
3. Claude 分析：
   - ChatController 收到请求 13:05:23.123
   - ChatService 调用 DeepSeek 13:05:23.456
   - DeepSeek 返回 200 OK 13:05:24.789
   - 发现：返回内容被截断（content.length() > 4096）
4. 结论：响应长度超过限制，需要调整配置

---

🛠️ 故障排查清单

问题：logs/ 目录没有生成

检查：

1. 项目是否启动成功？
2. 查看控制台是否有 Logback 错误
3. 检查 logback-spring.xml 语法

解决：

# 验证配置
bash scripts/verify-logging.sh

问题：日志文件为空

检查：

1. 日志级别是否太高（改为 DEBUG）
2. 是否触发了对应的功能（如 aiops.log 需要点击 AI Ops）

解决：

# application.yml
logging:
  level:
    org.example: DEBUG  # 确保是 DEBUG

问题：控制台看不到彩色日志

原因：Windows CMD 不支持 ANSI 颜色

解决：

• 使用 Git Bash
• 使用 PowerShell 7+
• 使用 Windows Terminal
• 或只看文件日志（无影响）

---

📝 配置调整

调整日志级别

编辑 src/main/resources/logback-spring.xml：

<!-- 只看 ERROR 和 WARN -->
<logger name="org.example" level="WARN" additivity="false">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="ASYNC_FILE_ALL"/>
</logger>

<!-- 增加某个类的详细日志 -->
<logger name="org.example.service.RagService" level="TRACE" additivity="false">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="FILE_ALL"/>
</logger>

调整滚动策略

<!-- 保留 90 天 -->
<maxHistory>90</maxHistory>

<!-- 单文件最大 50MB -->
<maxFileSize>50MB</maxFileSize>

<!-- 总大小 5GB -->
<totalSizeCap>5GB</totalSizeCap>

添加新的专用日志文件

<!-- 新增 RAG 专用日志 -->
<appender name="FILE_RAG" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${LOG_PATH}/rag.log</file>
    <!-- ... -->
</appender>

<logger name="org.example.service.RagService" level="DEBUG" additivity="false">
    <appender-ref ref="FILE_RAG"/>
</logger>

---

🎯 下一步

立即验证

1. 启动项目：

   mvn spring-boot:run
   

2. 检查日志文件生成：

   ls -lh logs/
   

   应该看到 application.log 立即生成。

3. 触发功能并查看专用日志：

   • 发送一条对话 → logs/chat.log 出现
   • 点击 AI Ops → logs/aiops.log 出现

4. 在 Claude Code 中分析：

   ! tail -n 50 logs/application.log
   

集成到开发流程

1. 每次调试新功能：

   ! tail -f logs/application.log
   

   在另一个终端实时查看日志。

2. 提交代码前：

   Read logs/application-error.log
   

   确保没有遗漏的错误。

3. 性能优化时：

   Grep pattern="耗时.*ms" path=logs/aiops.log
   

   提取所有耗时日志分析瓶颈。

---

📚 相关文档

• 详细指南：docs/日志配置与分析指南.md
• 配置文件：src/main/resources/logback-spring.xml
• 验证脚本：scripts/verify-logging.sh / scripts/verify-logging.bat

---

🎉 配置完成！ 现在 Claude 可以通过读取日志文件来分析你的项目运行情况了。