From 42b76c4de55a89d2416dc3d04037008488521e55 Mon Sep 17 00:00:00 2001 From: Misaka Date: Sat, 4 Apr 2026 10:54:18 +0800 Subject: [PATCH] docs(logging): add comprehensive logging operations guide --- docs/LOGGING_GUIDE.md | 547 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 docs/LOGGING_GUIDE.md diff --git a/docs/LOGGING_GUIDE.md b/docs/LOGGING_GUIDE.md new file mode 100644 index 0000000..27ecd3c --- /dev/null +++ b/docs/LOGGING_GUIDE.md @@ -0,0 +1,547 @@ +# ERPAuto 日志查询指南 + +## 概述 + +> 本指南用于帮助运维和开发人员使用日志系统快速排查问题。 +> +> **P0 升级**：日志系统已增强 requestId 追踪、性能监控、完整错误上下文。 + +--- + +## 日志字段说明 + +### 新增核心字段（P0 升级） + +| 字段 | 类型 | 说明 | 示例 | +| --------------- | ------- | ------------------------- | ---------------------------------------- | +| `requestId` | string | 请求唯一标识符（UUID v4） | `"f833980c-7b11-4c13-9c39-7c8890eb8b2f"` | +| `userId` | string | 执行操作的用户 ID | `"admin"` | +| `operation` | string | 操作类型 | `"extract"`, `"clean"`, `"validate"` | +| `duration` | number | 操作耗时（毫秒） | `1523` | +| `slow` | boolean | 是否为慢操作（> 阈值） | `true` | +| `batchId` | string | 批次 ID | `"B20260404-001"` | +| `tableName` | string | 数据库表名 | `"DiscreteMaterialPlan"` | +| `operationType` | string | 数据库操作类型 | `"INSERT"`, `"DELETE"`, `"UPDATE"` | +| `recordCount` | number | 记录数 | `150` | +| `fileSize` | number | 文件大小（字节） | `1048576` | + +### 业务上下文字段 + +| 字段 | 场景 | 说明 | +| ------------------------ | ----------------- | ---------------------------------- | +| `orderNumbers` | Extractor/Cleaner | 订单号列表 | +| `materialCodes` | Cleaner | 物料代码列表 | +| `downloadDir` | Extractor | 下载目录路径 | +| `dryRun` | Cleaner | 是否为干运行模式 | +| `mode` | Validation | 验证模式（`database_filtered` 等） | +| `useSharedProductionIds` | Validation | 是否使用共享 Production ID | +| `configPath` | Config | 配置文件路径 | +| `isDev` | Config | 是否为开发环境 | +| `version` | Update | 应用版本号 | +| `channel` | Update | 更新通道（`stable`/`preview`） | + +--- + +## 日志查询工具与脚本 + +### PowerShell 查询脚本 + +#### 1. 按 requestId 追踪完整请求链路 + +```powershell +# 查找特定 requestId 的所有日志 +$requestId = "f833980c-7b11-4c13-9c39-7c8890eb8b2f" +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.requestId -eq $requestId } | + Sort-Object timestamp | + Format-Table timestamp, level, message, context -AutoSize +``` + +**用途**：完整追踪一个请求的所有操作 + +--- + +#### 2. 查找慢操作（> 2 秒） + +```powershell +# 查找所有慢操作 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.duration -gt 2000 } | + Format-Table timestamp, operation, duration, message -AutoSize +``` + +**用途**：识别性能瓶颈 + +--- + +#### 3. 查找特定用户的所有操作 + +```powershell +# 按 userId 筛选日志 +$userId = "admin" +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.userId -eq $userId } | + Sort-Object timestamp | + Format-Table timestamp, operation, level, message -AutoSize +``` + +**用途**：审计用户操作 + +--- + +#### 4. 查找特定时间段内的错误 + +```powershell +# 查找最近 1 小时的错误 +$startTime = (Get-Date).AddHours(-1) +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\error-*.log" | + ConvertFrom-Json | + Where-Object { [datetime]::Parse($_.timestamp) -gt $startTime } | + Format-Table timestamp, message, error -AutoSize +``` + +**用途**：故障排查 + +--- + +#### 5. 按 operation 统计操作频率 + +```powershell +# 统计各 operation 的执行次数 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.operation } | + Group-Object operation | + Sort-Object Count -Descending | + Format-Table Name, Count -AutoSize +``` + +**用途**：了解系统使用情况 + +--- + +### Linux/Mac Bash 查询 + +```bash +# 按 requestId 过滤 +cat app-*.log | jq 'select(.requestId == "f833980c-7b11-4c13-9c39-7c8890eb8b2f")' + +# 查找错误日志 +cat error-*.log | jq '.' + +# 查找慢操作 +cat app-*.log | jq 'select(.duration > 2000)' + +# 统计 operation 频率 +cat app-*.log | jq -r '.operation' | sort | uniq -c | sort -rn +``` + +--- + +## 常见故障排查场景 + +### 场景 1：数据提取失败 + +**症状**：用户报告 "提取任务失败" + +**排查步骤**： + +```mermaid +flowchart TD + A[用户报告提取失败] --> B[定位 requestId] + B --> C[查看完整请求链路] + C --> D{错误类型？} + D -->|网络错误 | E[检查 ERP 连接] + D -->|数据库错误 | F[检查数据库连接] + D -->|文件错误 | G[检查文件权限] + E --> H[修复网络问题] + F --> H + G --> H + H --> I[重新执行提取] +``` + +**日志查询**： + +```powershell +# 1. 找到提取相关的错误日志 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\error-*.log" | + ConvertFrom-Json | + Where-Object { $_.operation -eq "extract" -and $_.message -like "*失败*" } | + Format-List timestamp, requestId, error, orderNumbers +``` + +**排查要点**： + +1. 查找 `operation: "extract"`的日志 +2. 提取`requestId`用于全链路追踪 +3. 检查`error`字段的具体错误信息 +4. 查看`orderNumbers`确定哪些订单失败 + +--- + +### 场景 2：物料清理执行缓慢 + +**症状**：用户报告 "清理任务太慢" + +**排查步骤**： + +```mermaid +flowchart TD + A[清理缓慢报告] --> B[查找慢操作] + B --> C{哪个阶段慢？} + C -->|批量处理 | D[检查订单数量/物料数量] + C -->|重试操作 | E[检查 ERP 响应时间] + C -->|数据库操作 | F[检查数据库性能] + D --> G[优化批量大小] + E --> G + F --> G +``` + +**日志查询**： + +```powershell +# 1. 查找清理相关的慢操作 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.operation -eq "cleaner" -and $_.duration -gt 5000 } | + Format-List timestamp, requestId, duration, slow, totalOrders, totalMaterials +``` + +**排查要点**： + +1. 查找 `duration > 5000ms` 的清理操作 +2. 检查`totalOrders`和`totalMaterials` 确认数据量 +3. 查看 `slow: true` 的批处理日志 + +--- + +### 场景 3：登录失败 + +**症状**：用户无法登录 + +**排查步骤**： + +```mermaid +flowchart TD + A[登录失败] --> B[查找认证错误] + B --> C{错误类型？} + C -->|凭证错误 | D[检查用户名/密码] + C -->|ERP 连接错误 | E[检查 ERP 服务状态] + C -->|会话错误 | F[检查会话管理] + D --> G[修正登录信息] + E --> G + F --> G +``` + +**日志查询**： + +```powershell +# 1. 查找认证相关的错误 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\error-*.log" | + ConvertFrom-Json | + Where-Object { $_.userId -eq "admin" -and $_.message -like "*login*" } | + Format-List timestamp, requestId, error, userId, username +``` + +**排查要点**： + +1. 查找 `operation: "login"`或`message` 包含"login"的日志 +2. 检查 `userId` 和`username` +3. 查看`error`字段的具体错误信息 + +--- + +### 场景 4：数据库插入失败 + +**症状**：数据无法保存到数据库 + +**排查步骤**： + +```mermaid +flowchart TD + A[数据库插入失败] --> B[查找数据库错误] + B --> C{错误类型？} + C -->|连接错误 | D[检查数据库服务] + C -->|SQL 语法错误 | E[检查 SQL 语句] + C -->|约束错误 | F[检查数据完整性] + D --> G[修复数据库问题] + E --> G + F --> G +``` + +**日志查询**： + +```powershell +# 1. 查找数据库相关的错误 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\error-*.log" | + ConvertFrom-Json | + Where-Object { $_.operationType -eq "INSERT" } | + Format-List timestamp, requestId, operationType, tableName, error +``` + +**排查要点**： + +1. 查找 `operationType: "INSERT"`的日志 +2. 检查`tableName` 确定哪个表失败 +3. 查看`error`字段的具体错误信息 + +--- + +### 场景 5：配置文件读取失败 + +**症状**：应用启动失败，提示配置错误 + +**排查步骤**： + +```mermaid +flowchart TD + A[配置读取失败] --> B[查找配置相关错误] + B --> C{错误类型？} + C -->|文件不存在 | D[检查配置文件路径] + C -->|解析错误 | E[检查 YAML 格式] + C -->|验证错误 | F[检查配置字段] + D --> G[修复配置问题] + E --> G + F --> G +``` + +**日志查询**： + +```powershell +# 1. 查找配置相关的错误 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\error-*.log" | + ConvertFrom-Json | + Where-Object { $_.configPath } | + Format-List timestamp, requestId, configPath, isDev, error +``` + +**排查要点**： + +1. 查找 `configPath` 字段的日志 +2. 检查 `isDev` 确定环境（开发/生产） +3. 查看`error`字段的具体错误信息 + +--- + +### 场景 6：文件上传失败 + +**症状**：文件无法上传到 RustFS + +**排查步骤**： + +**日志查询**： + +```powershell +# 1. 查找上传相关的错误 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\error-*.log" | + ConvertFrom-Json | + Where-Object { $_.fileSize -or $_.message -like "*upload*" } | + Format-List timestamp, requestId, fileSize, endpoint, bucket, error +``` + +**排查要点**： + +1. 查找 `fileSize` 字段的日志（表示文件操作） +2. 检查 `endpoint`和`bucket` 配置 +3. 查看`error`字段的具体错误信息 + +--- + +### 场景 7：验证任务无数据返回 + +**症状**：验证任务执行成功但无数据 + +**排查步骤**： + +**日志查询**： + +```powershell +# 1. 查找验证相关的日志 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.operation -eq "validate" } | + Format-List timestamp, requestId, mode, useSharedProductionIds, recordCount +``` + +**排查要点**： + +1. 查找 `operation: "validate"`的日志 +2. 检查 `mode`字段（数据来源） +3. 查看`useSharedProductionIds`和`recordCount` + +--- + +## 日志最佳实践 + +### 1. 开发环境 vs 生产环境 + +```mermaid +flowchart LR + A[日志级别配置] --> B{环境？} + B -->|开发 | C[DEBUG 级别
详细信息] + B -->|生产 | D[INFO 级别
业务操作] + C --> E[调试问题] + D --> F[监控运行] +``` + +**配置示例**： + +```yaml +# config.yaml +logging: + level: debug # 开发环境 + # level: info # 生产环境 +``` + +--- + +### 2. 敏感信息保护 + +**永远不要记录**： + +- ❌ 密码 +- ❌ Token/密钥 +- ❌ 数据库连接字符串 +- ❌ 用户个人信息 + +**正确做法**： + +```typescript +// ❌ 错误：记录敏感信息 +log.error('Login failed', { password: userPassword }) + +// ✅ 正确：使用脱敏信息 +log.error('Login failed', { + userId: 'admin', + reason: 'invalid_credentials' // 仅记录原因 +}) +``` + +--- + +### 3. 错误日志应该包含 + +**完整上下文**： + +```typescript +log.error('Database insert failed', { + requestId: getRequestId(), // 自动注入 + operation: 'insert-materials', + userId: 'admin', + tableName: 'DiscreteMaterialPlan', + recordCount: 150, + error: error.message, + orderNumbers: ['SO001', 'SO002'] +}) +``` + +--- + +### 4. 性能监控 + +**关键指标**： + +- `duration > 1000ms`：一般警告 +- `duration > 5000ms`：严重警告 +- `duration > 10000ms`：需要立即调查 + +**监控脚本**： + +```powershell +# 每小时生成性能报告 +Get-Content "C:\Users\pengq\AppData\Roaming\erpauto\logs\app-*.log" | + ConvertFrom-Json | + Where-Object { $_.duration -gt 1000 } | + Group-Object operation | + ForEach-Object { + [PSCustomObject]@{ + Operation = $_.Name + SlowOperations = $_.Count + AvgDuration = [math]::Round(($_.Group | Measure-Object duration -Average).Average, 2) + MaxDuration = [math]::Round(($_.Group | Measure-Object duration -Maximum).Maximum, 2) + } + } | Format-Table -AutoSize +``` + +--- + +## 日志文件管理 + +### 文件位置 + +| 环境 | 路径 | +| -------- | ------------------------------------------------- | +| **开发** | `D:\FileLib\Projects\CodeMigration\ERPAuto\logs\` | +| **生产** | `C:\Users\\AppData\Roaming\erpauto\logs\` | + +### 文件命名 + +| 类型 | 命名格式 | 说明 | +| -------- | ------------------------ | ------------------ | +| 应用日志 | `app-YYYY-MM-DD.log` | 所有业务日志 | +| 错误日志 | `error-YYYY-MM-DD.log` | 仅错误级别日志 | +| 审计日志 | `audit-YYYY-MM-DD.jsonl` | 用户操作审计 | +| 压缩归档 | `*.log.gz` | 超过保留期限的日志 | + +### 保留策略 + +```yaml +# config.yaml +logging: + appRetention: 14 # 应用日志保留 14 天 + auditRetention: 30 # 审计日志保留 30 天 +``` + +--- + +## 故障排查流程图 + +### 通用排查流程 + +```mermaid +flowchart TD + A[收到故障报告] --> B[确定故障类型] + B --> C{故障类型？} + C -->|功能错误 | D[查找相关 error 日志] + C -->|性能问题 | E[查找慢操作日志] + C -->|数据问题 | F[查找数据操作日志] + D --> G[定位 requestId] + E --> G + F --> G + G --> H[追踪完整请求链路] + H --> I[分析错误根因] + I --> J[制定修复方案] + J --> K[执行修复] + K --> L[验证修复效果] +``` + +--- + +## 总结 + +### 快速参考 + +| 需求 | 查询字段 | +| ---------- | ------------------------ | +| 完整追踪 | `requestId` | +| 性能排查 | `duration`, `slow` | +| 用户审计 | `userId` | +| 错误分析 | `error`, `operationType` | +| 数据库问题 | `tableName`, `records` | +| 文件问题 | `fileSize`, `filePath` | + +### 联系支持 + +如遇日志相关问题，请联系技术支持团队并提供： + +1. 故障时间段 +2. 相关 `requestId` +3. 错误日志内容 + +--- + +_文档版本：P0 Enhanced Logging_ +_更新日期：2026-04-04_