293 lines
7.4 KiB
Markdown
293 lines
7.4 KiB
Markdown
# 日志配置与分析指南
|
||
|
||
> 配置日期：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 工具分析日志，帮助你调试问题。
|