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 配置（已添加）

```yaml
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. 查看实时日志

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

```bash
# 查看最新 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. 搜索特定日志

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

```bash
# 搜索包含 "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. 读取对应时间段的日志
   ```bash
   ! grep "2026-05-30 13:" logs/aiops.log
   ```
3. Claude 自动分析堆栈跟踪、错误信息、性能指标

---

## 📊 日志级别说明

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

---

## 🎯 常见分析场景

### 场景 1：AI Ops 分析耗时

**目标**：分析哪个环节慢

```bash
! 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 调用问题

```bash
! 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 连接问题

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

```bash
! 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 响应的完整链路

```bash
! 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 的日志
```

---

## 📝 日志最佳实践

### 开发时

```java
// ✅ 好的日志
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. 启动项目
```bash
mvn spring-boot:run
```

### 2. 验证日志文件生成
```bash
ls -lh logs/
```

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

### 3. 测试日志输出

访问 `http://localhost:9900`，发送一条消息，然后：
```bash
! 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 工具分析日志，帮助你调试问题。