276 lines
6.2 KiB
Markdown
276 lines
6.2 KiB
Markdown
# 日志配置完成总结
|
||
|
||
## ✅ 已完成的工作
|
||
|
||
### 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：启动项目后手动查看
|
||
|
||
```bash
|
||
# 启动项目
|
||
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
|
||
# 验证配置
|
||
bash scripts/verify-logging.sh
|
||
```
|
||
|
||
### 问题：日志文件为空
|
||
|
||
**检查**：
|
||
1. 日志级别是否太高（改为 DEBUG）
|
||
2. 是否触发了对应的功能（如 aiops.log 需要点击 AI Ops）
|
||
|
||
**解决**：
|
||
```yaml
|
||
# application.yml
|
||
logging:
|
||
level:
|
||
org.example: DEBUG # 确保是 DEBUG
|
||
```
|
||
|
||
### 问题：控制台看不到彩色日志
|
||
|
||
**原因**：Windows CMD 不支持 ANSI 颜色
|
||
|
||
**解决**：
|
||
- 使用 Git Bash
|
||
- 使用 PowerShell 7+
|
||
- 使用 Windows Terminal
|
||
- 或只看文件日志（无影响）
|
||
|
||
---
|
||
|
||
## 📝 配置调整
|
||
|
||
### 调整日志级别
|
||
|
||
编辑 `src/main/resources/logback-spring.xml`：
|
||
|
||
```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>
|
||
```
|
||
|
||
### 调整滚动策略
|
||
|
||
```xml
|
||
<!-- 保留 90 天 -->
|
||
<maxHistory>90</maxHistory>
|
||
|
||
<!-- 单文件最大 50MB -->
|
||
<maxFileSize>50MB</maxFileSize>
|
||
|
||
<!-- 总大小 5GB -->
|
||
<totalSizeCap>5GB</totalSizeCap>
|
||
```
|
||
|
||
### 添加新的专用日志文件
|
||
|
||
```xml
|
||
<!-- 新增 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. **启动项目**：
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
2. **检查日志文件生成**：
|
||
```bash
|
||
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](./日志配置与分析指南.md)
|
||
- **配置文件**：`src/main/resources/logback-spring.xml`
|
||
- **验证脚本**：`scripts/verify-logging.sh` / `scripts/verify-logging.bat`
|
||
|
||
---
|
||
|
||
> 🎉 **配置完成！** 现在 Claude 可以通过读取日志文件来分析你的项目运行情况了。
|