# 日志配置完成总结

## ✅ 已完成的工作

### 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="com.superbiz.agent.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="com.superbiz.agent.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 可以通过读取日志文件来分析你的项目运行情况了。