# 📊 生产环境日志系统使用指南

## 概述

生产级日志系统确保所有交易活动都被完整记录，方便事后复盘和问题排查。

---

## 🏗️ 日志架构

### 日志文件结构

```
logs/
├── trading-2025-10-02.log          # 主日志（所有级别）
├── error-2025-10-02.log            # 错误日志
├── warning-2025-10-02.log          # 警告日志
├── audit/
│   └── audit-2025-10-02.log        # 审计日志（关键操作）
└── performance/
    └── perf-2025-10-02.log         # 性能指标
```

### 日志保留策略

| 日志类型 | 单文件大小限制 | 保留时间 |
|---------|--------------|---------|
| 主日志 | 100MB | 30天 |
| 错误日志 | 50MB | 90天 |
| 警告日志 | 50MB | 30天 |
| 审计日志 | 100MB | 365天 |
| 性能日志 | 50MB | 7天 |

---

## 📝 记录的关键事件

### 1. 会话生命周期
- `SESSION_START` - 策略启动
- `SESSION_END` - 策略停止

### 2. 交易周期
- `CYCLE_START` - 周期开始
- `CYCLE_END` - 周期结束（含性能数据）
- `SIGNALS_GENERATED` - 生成的交易信号

### 3. 订单事件
- `ORDER_SUBMIT` - 订单提交
- `ORDER_SUCCESS` - 订单成功
- `ORDER_FAILED` - 订单失败
- `ORDER_CANCELLED` - 订单取消
- `ORDER_FILLED` - 订单成交

### 4. 账户状态
- `BALANCE_UPDATE` - 余额更新
- `POSITION_UPDATE` - 仓位更新

### 5. 风险控制
- `MARGIN_WARNING` - 保证金警告
- `REDUCE_SIGNAL` - 减仓信号
- `DELTA_ASSESSMENT` - Delta 评估

### 6. 定价决策
- `PRICING_DECISION` - 定价逻辑记录

---

## 🔍 日志查询示例

### 查看今天的所有错误

```bash
cat logs/error-$(date +%Y-%m-%d).log | jq '.'
```

### 查看特定账户的订单

```bash
cat logs/audit/audit-2025-10-02.log | jq 'select(.accountId == "account-1") | select(.message | contains("ORDER"))'
```

### 统计今天的订单成功率

```bash
# 总订单数
grep "ORDER_SUBMIT" logs/audit/audit-2025-10-02.log | wc -l

# 成功订单数
grep "ORDER_SUCCESS" logs/audit/audit-2025-10-02.log | wc -l
```

### 查看保证金警告

```bash
cat logs/audit/audit-2025-10-02.log | jq 'select(.message == "MARGIN_WARNING")'
```

### 查看 Delta 评估历史

```bash
cat logs/audit/audit-2025-10-02.log | jq 'select(.message == "DELTA_ASSESSMENT") | {timestamp, weightedDelta, exceedsTolerance, recommendation}'
```

### 分析性能慢的周期

```bash
cat logs/audit/audit-2025-10-02.log | jq 'select(.message == "CYCLE_END") | select(.duration > 10000) | {timestamp, cycleId, duration}'
```

---

## 🛠️ 日志分析工具

### 使用 analyze-logs.ts 工具

```bash
# 分析今天的日志
tsx scripts/analyze-logs.ts

# 分析指定日期的日志
tsx scripts/analyze-logs.ts 2025-10-02
```

### 输出示例

```
╔════════════════════════════════════════════════╗
║  日志分析报告 - 2025-10-02
╚════════════════════════════════════════════════╝

📊 === 交易概览 ===
  会话数: 1
  交易周期数: 240
  完成周期数: 240
  首次启动: 2025-10-02 09:00:00.123
  最后停止: 2025-10-02 18:00:00.456
  总周期数: 240

📋 === 订单分析 ===
  提交订单: 480
  成功订单: 476
  失败订单: 4
  取消订单: 120
  成交订单: 356
  成功率: 99.17%

  按账户分布:
    account-1: 240 单
    account-2: 240 单

💰 === 账户余额变化 ===
  账户: account-1
    起始余额: 10000.00 (可用: 9500.00)
    结束余额: 10123.45 (可用: 9623.45)
    变化: +123.45 (+1.23%)
    更新次数: 245

⚖️  === Delta 分析 ===
  评估次数: 240
  超过容忍度: 3 次
  Delta 范围: [-0.000123, 0.000098]
  Delta 平均: 0.000012

🚨 === 保证金警告 ===
  ✅ 无保证金警告

⚡ === 性能分析 ===
  周期耗时:
    最快: 1234ms
    最慢: 8976ms
    平均: 3456ms

❌ === 错误分析 ===
  ✅ 无错误记录
```

---

## 📊 复盘检查清单

### 每日检查 (必须)

1. **订单成功率**
   ```bash
   tsx scripts/analyze-logs.ts $(date +%Y-%m-%d)
   ```
   - 成功率应 > 95%
   - 如低于 95%，检查失败原因

2. **保证金警告**
   ```bash
   grep "MARGIN_WARNING" logs/audit/audit-$(date +%Y-%m-%d).log
   ```
   - 不应有 emergency 级别警告
   - 如有，检查仓位管理

3. **Delta 偏离**
   ```bash
   grep "DELTA_ASSESSMENT" logs/audit/audit-$(date +%Y-%m-%d).log | jq 'select(.exceedsTolerance == true)'
   ```
   - Delta 偏离次数应 < 5%
   - 如频繁偏离，检查对冲逻辑

4. **错误日志**
   ```bash
   cat logs/error-$(date +%Y-%m-%d).log | jq '.'
   ```
   - 不应有重复错误
   - 关注 API 连接错误

### 每周检查 (建议)

1. **账户盈亏**
   - 对比每天的余额变化
   - 确认符合预期收益率

2. **性能趋势**
   - 检查平均周期耗时是否增加
   - 如持续增长，需优化代码

3. **取消订单比例**
   - 计算取消订单 / 总订单比例
   - 如 > 50%，考虑调整定价策略

---

## 🚨 告警阈值

### 立即处理

| 事件 | 阈值 | 操作 |
|-----|------|------|
| 订单成功率 | < 90% | 检查 API 连接和参数 |
| 保证金利用率 | > 95% | 立即减仓 |
| Delta 偏离 | > 0.01 | 检查对冲执行 |
| 连续失败订单 | > 10 | 暂停策略，检查日志 |

### 需要关注

| 事件 | 阈值 | 操作 |
|-----|------|------|
| 订单成功率 | 90-95% | 监控并分析原因 |
| 保证金利用率 | 85-95% | 准备减仓 |
| 周期耗时 | > 10s | 检查性能瓶颈 |
| 取消订单比例 | > 50% | 优化定价策略 |

---

## 🔧 日志级别说明

| 级别 | 用途 | 示例 |
|-----|------|------|
| **error** | 严重错误，需要立即处理 | API 调用失败、订单提交异常 |
| **warn** | 警告，可能影响策略 | 保证金警告、Delta 偏离 |
| **info** | 正常操作信息 | 订单提交、余额更新 |
| **debug** | 调试信息 | WebSocket 消息、定价计算 |

---

## 💡 最佳实践

### 1. 定期归档

```bash
# 每月归档旧日志
tar -czf logs_archive_2025-09.tar.gz logs/*2025-09*.log
rm logs/*2025-09*.log
```

### 2. 监控磁盘空间

```bash
# 检查日志目录大小
du -sh logs/
```

### 3. 自动化检查

创建 cron 任务每日运行分析工具：

```bash
# crontab -e
0 9 * * * cd /path/to/pecifica && tsx scripts/analyze-logs.ts $(date -d yesterday +\%Y-\%m-\%d) > daily_report.txt
```

### 4. 备份审计日志

审计日志包含所有交易记录，建议定期备份到云存储。

```bash
# 备份到 S3/OSS
aws s3 sync logs/audit/ s3://your-bucket/trading-logs/audit/
```

---

## 🆘 常见问题

### Q: 日志文件太大怎么办？

A: 日志会自动轮转，旧文件会被压缩。可以调整 `maxSize` 和 `maxFiles` 参数。

### Q: 如何查找特定订单的完整生命周期？

A:
```bash
orderId="12345"
cat logs/audit/audit-*.log | jq "select(.orderId == \"$orderId\")" | jq -s 'sort_by(.timestamp)'
```

### Q: 如何快速定位性能问题？

A:
```bash
# 查看最慢的 10 个周期
cat logs/audit/audit-$(date +%Y-%m-%d).log | jq 'select(.message == "CYCLE_END")' | jq -s 'sort_by(.duration) | reverse | .[0:10]'
```

### Q: 日志里没有我期望的信息？

A: 检查是否在代码中调用了相应的日志方法。参考 `ProductionLogger.ts` 的 API。

---

## 📚 相关文档

- [ProductionLogger API](src/utils/ProductionLogger.ts)
- [日志分析工具](scripts/analyze-logs.ts)
- [策略架构](COMPREHENSIVE_AUDIT.md)

---

**记住**: 日志是复盘的唯一依据，确保所有关键操作都被记录！