# IBKR MCP 日志系统文档
## 概述
IBKR MCP 项目采用了现代化的日志系统架构，基于 **Loguru** 日志库构建，提供统一、高效、结构化的日志记录解决方案。本文档详细介绍了系统的日志架构、配置和使用方法。
## 核心特性
### 1. 基于 Loguru 的统一日志系统
项目选择 [Loguru](https://github.com/Delgan/loguru) 作为核心日志库，替代了 Python 标准库的 logging 模块，提供以下优势：
- **零配置使用**：无需复杂的 setup，开箱即用
- **结构化日志**：支持 JSON 格式输出，便于日志分析
- **自动格式化**：优雅的日志格式，包含时间戳、级别、模块信息
- **异常捕获**：自动捕获和记录异常堆栈信息
### 2. 分布式日志记录
日志系统在项目的各个层面都有集成：
```
src/ibkr_mcp/
├── services/
│ ├── market_data.py # 市场数据服务日志
│ ├── portfolio.py # 投资组合日志
│ └── risk_service.py # 风险服务日志
├── infrastructure/
│ ├── database.py # 数据库操作日志
│ ├── repositories.py # 数据仓库日志
│ └── models.py # 数据模型日志
├── strategies/
│ ├── base.py # 策略基础日志
│ ├── strategy_*.py # 各策略模块日志
├── common/
│ ├── positions.py # 持仓管理日志
│ ├── greeks.py # 希腊字母计算日志
│ ├── option_data.py # 期权数据日志
│ ├── market_state.py # 市场状态日志
│ └── stock_data.py # 股票数据日志
└── server.py # 服务器启动日志
```
### 3. 日志级别体系
系统采用标准的多级别日志记录：
- **DEBUG** (`logger.debug`): 详细的调试信息，用于开发调试
- **INFO** (`logger.info`): 一般信息，记录正常操作流程
- **WARNING** (`logger.warning`): 警告信息，记录非致命错误
- **ERROR** (`logger.error`): 错误信息，记录可恢复的错误
- **EXCEPTION** (`logger.exception`): 异常信息，自动捕获堆栈跟踪
## 日志使用示例
### 1. 基本日志记录
```python
from loguru import logger
# 信息日志
logger.info("数据库连接成功")
logger.info("开始获取期权链数据", symbol="AAPL", count=10)
# 警告日志
logger.warning("配置文件未找到，使用默认配置")
logger.warning("IBKR 连接断开，尝试重连", attempt=3)
# 错误日志
logger.error("数据库连接失败", error=str(e))
logger.opt(exception=e).error("期权数据获取异常")
```
### 2. 结构化日志记录
```python
# 带上下文信息的日志
logger.info(
"策略执行完成",
strategy="PutCreditSpread",
symbol="SPY",
signal="BUY",
confidence=0.85,
timestamp="2025-12-18T10:30:00Z"
)
# 性能监控日志
logger.debug("数据库查询耗时", query="SELECT * FROM positions", duration_ms=156)
```
### 3. 异常处理
```python
try:
result = fetch_option_chain(symbol)
except Exception as e:
logger.exception("获取期权链失败", symbol=symbol)
raise
# 或者使用 opt(exception=e)
try:
risky_operation()
except Exception as e:
logger.opt(exception=e).error("操作失败", operation="fetch_data")
```
## 关键模块日志分析
### 1. 市场数据服务 (market_data.py)
```python
# 调度器日志
logger.info("调度器启动，共 {count} 个标的", count=len(symbols))
logger.info("调度器已运行中")
logger.warning("配置加载失败，使用默认配置", error=str(e))
# 数据获取日志
logger.info("开始获取期权链", symbol=symbol, mode=mode)
logger.info("期权链获取成功", symbol=symbol, contracts=len(contracts))
logger.opt(exception=e).error("期权链获取失败", symbol=symbol)
```
### 2. 数据库操作 (database.py)
```python
# 连接管理
logger.info("数据库连接已建立", url=sanitize_db_url(db_url))
# 事务管理
logger.exception("数据库会话错误，执行回滚")
logger.debug("数据库健康检查通过")
# 初始化日志
logger.info("数据库架构初始化成功")
logger.error("数据库初始化失败", error=str(e))
```
### 3. 策略模块 (strategies/)
```python
# 策略状态记录
logger.info("策略执行", strategy=self.name, signal=signal.signal_type)
# 市场状态
logger.info("市场状态评估", symbol=symbol, state=market_state.state)
# 异常处理
logger.exception("策略执行失败", strategy=self.name, symbol=symbol)
```
### 4. 持仓管理 (positions.py)
```python
# 持仓加载
logger.info("加载持仓数据", count=len(positions))
logger.warning("未找到持仓信息")
# IBKR 连接
logger.exception("从 IBKR 加载持仓失败")
logger.info("PositionStore 初始化完成")
# 事件监听
logger.debug("收到持仓更新事件", symbol=symbol, position=position)
```
## 日志配置
### 1. 默认配置
项目使用 Loguru 的默认配置，通常包括：
- **输出**: 标准输出 (stdout)
- **格式**: 时间戳 + 级别 + 模块 + 消息
- **级别**: INFO (生产环境) / DEBUG (开发环境)
### 2. 运行时配置
服务器启动时可通过环境变量配置日志级别：
```python
# 在 server.py 中
config = uvicorn.Config(
app,
host=host,
port=port,
log_level=mcp.settings.log_level.lower(), # 从环境变量读取
)
```
### 3. 自定义日志配置
如需自定义日志行为，可在应用启动时添加配置：
```python
from loguru import logger
import sys
# 移除默认处理器
logger.remove()
# 添加自定义处理器
logger.add(
sys.stdout,
format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
"<level>{level: <8}</level> | "
"<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
"<level>{message}</level>",
level="INFO"
)
# 添加文件处理器
logger.add(
"logs/ibkr_mcp.log",
rotation="10 MB",
retention="30 days",
format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
level="DEBUG"
)
```
## 最佳实践
### 1. 日志级别使用指南
- **DEBUG**: 详细的执行流程，用于问题诊断
```python
logger.debug("进入函数", function_name="fetch_option_chain", args=args)
```
- **INFO**: 关键业务流程节点
```python
logger.info("期权链数据已保存", symbol=symbol, path=file_path)
```
- **WARNING**: 需要关注但不中断流程的情况
```python
logger.warning("数据源不可用，使用缓存数据", source="IBKR", fallback="local")
```
- **ERROR**: 可恢复的错误
```python
logger.error("数据库连接失败，重试中", attempt=retry_count)
```
- **EXCEPTION**: 未捕获的异常
```python
logger.exception("无法处理请求", request_id=request_id)
```
### 2. 结构化日志原则
始终包含关键上下文信息：
```python
# ✅ 好的实践
logger.info(
"期权交易执行",
symbol="AAPL",
action="BUY",
quantity=10,
price=150.25,
timestamp=datetime.now().isoformat()
)
# ❌ 避免
logger.info("执行了交易")
```
### 3. 性能考虑
- 避免在高频循环中记录 DEBUG 日志
- 使用适当的日志级别过滤不必要的信息
- 对于性能敏感的代码块，考虑条件日志：
```python
if logger.is_enabled_for(logging.DEBUG):
start_time = time.time()
result = expensive_operation()
logger.debug("操作耗时 {duration}ms", duration=(time.time()-start_time)*1000)
else:
result = expensive_operation()
```
## 日志分析工具
### 1. 实时监控
使用 `tail` 命令实时查看日志：
```bash
# 查看实时日志
tail -f logs/ibkr_mcp.log
# 过滤特定级别的日志
tail -f logs/ibkr_mcp.log | grep "ERROR"
# 过滤特定模块的日志
tail -f logs/ibkr_mcp.log | grep "market_data"
```
### 2. 日志分析
使用 grep 进行日志分析：
```bash
# 统计错误数量
grep -c "ERROR" logs/ibkr_mcp.log
# 查看特定时间的日志
grep "2025-12-18 10:" logs/ibkr_mcp.log
# 分析策略执行情况
grep "策略执行" logs/ibkr_mcp.log | awk '{print $NF}'
```
### 3. 集成 ELK Stack
对于生产环境，建议集成 Elasticsearch + Logstash + Kibana：
```python
# 添加 Elasticsearch 处理器
logger.add(
"es://localhost:9200/ibkr_mcp_logs",
format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {message}",
level="INFO"
)
```
## 常见问题
### Q: 如何调整日志级别？
A: 通过环境变量设置：
```bash
export LOG_LEVEL=DEBUG # 开发环境
export LOG_LEVEL=INFO # 生产环境
```
### Q: 日志文件过大怎么办？
A: 使用 Loguru 的轮转功能：
```python
logger.add(
"logs/app.log",
rotation="10 MB", # 文件达到 10MB 时轮转
retention="30 days", # 保留 30 天
compression="gz", # 压缩旧日志
)
```
### Q: 如何在测试中禁用日志？
A: 使用 Loguru 的禁用功能：
```python
import logging
logger.disable("ibkr_mcp") # 禁用所有 ibkr_mcp 模块的日志
```
## 总结
IBKR MCP 的日志系统提供了：
1. **统一性**: 基于 Loguru 的标准化日志记录
2. **结构化**: 包含丰富上下文信息的结构化日志
3. **可观测性**: 完整覆盖系统各个层面的日志记录
4. **可扩展性**: 支持多种输出目标和分析工具集成
良好的日志系统是系统可维护性和可观测性的关键基础。建议开发者在所有关键业务逻辑中添加适当的日志记录，以便于问题诊断和性能监控。
---
*最后更新: 2025-12-18*
