414 lines
9.1 KiB
Markdown
414 lines
9.1 KiB
Markdown
# 日志记录功能使用指南
|
||
|
||
## 📋 概述
|
||
|
||
为所有运行脚本添加了日志记录功能，可以将终端输出同时保存到文本文件，方便后续分析和问题排查。
|
||
|
||
---
|
||
|
||
## 🎯 功能特点
|
||
|
||
1. **双向输出**：同时输出到终端和文件，不影响实时查看
|
||
2. **自动管理**：使用上下文管理器，自动处理文件开启/关闭
|
||
3. **灵活配置**：支持自定义文件名和日志目录
|
||
4. **时间戳命名**：默认使用时间戳生成唯一文件名
|
||
5. **无缝集成**：只需添加命令行参数，无需修改代码
|
||
|
||
---
|
||
|
||
## 🚀 快速使用
|
||
|
||
### 1. 基础用法
|
||
|
||
```bash
|
||
# 不启用日志（默认）
|
||
python Env/run_multiagent_env.py
|
||
|
||
# 启用日志记录
|
||
python Env/run_multiagent_env.py --log
|
||
|
||
# 或使用短选项
|
||
python Env/run_multiagent_env.py -l
|
||
```
|
||
|
||
### 2. 自定义文件名
|
||
|
||
```bash
|
||
# 使用自定义日志文件名
|
||
python Env/run_multiagent_env.py --log --log-file=my_test.log
|
||
|
||
# 测试脚本也支持
|
||
python Env/test_lane_filter.py --log --log-file=test_results.log
|
||
```
|
||
|
||
### 3. 组合使用调试和日志
|
||
|
||
```bash
|
||
# 测试脚本：调试模式 + 日志记录
|
||
python Env/test_lane_filter.py --debug --log
|
||
|
||
# 会生成类似：test_debug_20251021_123456.log
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 日志文件位置
|
||
|
||
默认日志目录：`Env/logs/`
|
||
|
||
### 文件命名规则
|
||
|
||
| 脚本 | 默认文件名格式 | 示例 |
|
||
|------|---------------|------|
|
||
| `run_multiagent_env.py` | `run_YYYYMMDD_HHMMSS.log` | `run_20251021_143022.log` |
|
||
| `run_multiagent_env_fast.py` | `run_fast.log` | `run_fast.log` |
|
||
| `test_lane_filter.py` | `test_{mode}_YYYYMMDD_HHMMSS.log` | `test_debug_20251021_143500.log` |
|
||
|
||
**说明**：
|
||
- `YYYYMMDD_HHMMSS` 是时间戳（年月日_时分秒）
|
||
- `{mode}` 是测试模式（`standard` 或 `debug`）
|
||
|
||
---
|
||
|
||
## 📝 所有支持的脚本
|
||
|
||
### 1. run_multiagent_env.py（标准运行脚本）
|
||
|
||
```bash
|
||
# 不启用日志
|
||
python Env/run_multiagent_env.py
|
||
|
||
# 启用日志（自动生成时间戳文件名）
|
||
python Env/run_multiagent_env.py --log
|
||
|
||
# 自定义文件名
|
||
python Env/run_multiagent_env.py --log --log-file=run_test1.log
|
||
```
|
||
|
||
**日志位置**：`Env/logs/run_YYYYMMDD_HHMMSS.log`
|
||
|
||
---
|
||
|
||
### 2. run_multiagent_env_fast.py（高性能版本）
|
||
|
||
```bash
|
||
# 启用日志
|
||
python Env/run_multiagent_env_fast.py --log
|
||
|
||
# 自定义文件名
|
||
python Env/run_multiagent_env_fast.py --log --log-file=fast_test.log
|
||
```
|
||
|
||
**日志位置**：`Env/logs/run_fast.log`（默认）
|
||
|
||
---
|
||
|
||
### 3. test_lane_filter.py（测试脚本）
|
||
|
||
```bash
|
||
# 标准测试 + 日志
|
||
python Env/test_lane_filter.py --log
|
||
|
||
# 调试测试 + 日志
|
||
python Env/test_lane_filter.py --debug --log
|
||
|
||
# 自定义文件名
|
||
python Env/test_lane_filter.py --log --log-file=my_test.log
|
||
|
||
# 组合使用
|
||
python Env/test_lane_filter.py --debug --log --log-file=debug_run.log
|
||
```
|
||
|
||
**日志位置**：
|
||
- 标准模式：`Env/logs/test_standard_YYYYMMDD_HHMMSS.log`
|
||
- 调试模式：`Env/logs/test_debug_YYYYMMDD_HHMMSS.log`
|
||
|
||
---
|
||
|
||
## 💻 编程接口
|
||
|
||
如果您想在代码中直接使用日志功能：
|
||
|
||
```python
|
||
from logger_utils import setup_logger
|
||
|
||
# 方式1：使用上下文管理器（推荐）
|
||
with setup_logger(log_file="my_log.log", log_dir="logs"):
|
||
print("这条消息会同时输出到终端和文件")
|
||
# 运行您的代码
|
||
# ...
|
||
|
||
# 方式2：手动管理
|
||
from logger_utils import LoggerContext
|
||
|
||
logger = LoggerContext(log_file="custom.log", log_dir="output")
|
||
logger.__enter__() # 开启日志
|
||
print("输出消息")
|
||
logger.__exit__(None, None, None) # 关闭日志
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 日志内容示例
|
||
|
||
### 标准运行
|
||
|
||
```
|
||
📝 日志记录已启用
|
||
📁 日志文件: Env/logs/run_20251021_143022.log
|
||
------------------------------------------------------------
|
||
💡 提示: 使用 --log 或 -l 参数启用日志记录
|
||
示例: python run_multiagent_env.py --log
|
||
自定义文件名: python run_multiagent_env.py --log --log-file=my_run.log
|
||
------------------------------------------------------------
|
||
[INFO] Environment: MultiAgentScenarioEnv
|
||
[INFO] MetaDrive version: 0.4.3
|
||
...
|
||
------------------------------------------------------------
|
||
✅ 日志已保存到: Env/logs/run_20251021_143022.log
|
||
```
|
||
|
||
### 调试模式
|
||
|
||
```
|
||
📝 日志记录已启用
|
||
📁 日志文件: Env/logs/test_debug_20251021_143500.log
|
||
------------------------------------------------------------
|
||
🐛 调试模式启用
|
||
============================================================
|
||
|
||
📍 场景信息统计:
|
||
- 总车道数: 123
|
||
- 有红绿灯的车道数: 0
|
||
⚠️ 场景中没有红绿灯！
|
||
|
||
🔍 开始车道过滤: 共 51 辆车待检测
|
||
...
|
||
------------------------------------------------------------
|
||
✅ 日志已保存到: Env/logs/test_debug_20251021_143500.log
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 高级配置
|
||
|
||
### 自定义日志目录
|
||
|
||
```python
|
||
from logger_utils import setup_logger
|
||
|
||
# 指定不同的日志目录
|
||
with setup_logger(log_file="test.log", log_dir="my_logs"):
|
||
print("日志会保存到 my_logs/test.log")
|
||
```
|
||
|
||
### 追加模式
|
||
|
||
```python
|
||
from logger_utils import setup_logger
|
||
|
||
# 追加到现有文件（而不是覆盖）
|
||
with setup_logger(log_file="test.log", mode='a'): # mode='a' 表示追加
|
||
print("这条消息会追加到文件末尾")
|
||
```
|
||
|
||
### 只重定向特定输出
|
||
|
||
```python
|
||
from logger_utils import LoggerContext
|
||
|
||
# 只重定向stdout，不重定向stderr
|
||
logger = LoggerContext(
|
||
log_file="test.log",
|
||
redirect_stdout=True, # 重定向标准输出
|
||
redirect_stderr=False # 不重定向错误输出
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 命令行参数总结
|
||
|
||
| 参数 | 短选项 | 说明 | 示例 |
|
||
|------|--------|------|------|
|
||
| `--log` | `-l` | 启用日志记录 | `--log` |
|
||
| `--log-file=NAME` | 无 | 指定日志文件名 | `--log-file=test.log` |
|
||
| `--debug` | `-d` | 启用调试模式（test_lane_filter.py） | `--debug` |
|
||
|
||
### 参数组合
|
||
|
||
```bash
|
||
# 示例1：标准模式 + 日志
|
||
python Env/test_lane_filter.py --log
|
||
|
||
# 示例2：调试模式 + 日志
|
||
python Env/test_lane_filter.py --debug --log
|
||
|
||
# 示例3：调试 + 自定义文件名
|
||
python Env/test_lane_filter.py -d --log --log-file=my_debug.log
|
||
|
||
# 示例4：所有参数
|
||
python Env/test_lane_filter.py --debug --log --log-file=full_test.log
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 常见问题
|
||
|
||
### Q1: 日志文件在哪里？
|
||
|
||
**A**: 默认在 `Env/logs/` 目录下。如果目录不存在，会自动创建。
|
||
|
||
```bash
|
||
# 查看所有日志文件
|
||
ls -lh Env/logs/
|
||
|
||
# 查看最新的日志
|
||
ls -lt Env/logs/ | head -5
|
||
```
|
||
|
||
---
|
||
|
||
### Q2: 如何查看日志内容？
|
||
|
||
**A**: 使用任何文本编辑器或命令行工具：
|
||
|
||
```bash
|
||
# 方式1：使用cat
|
||
cat Env/logs/run_20251021_143022.log
|
||
|
||
# 方式2：使用less（可翻页）
|
||
less Env/logs/run_20251021_143022.log
|
||
|
||
# 方式3：查看末尾内容
|
||
tail -n 50 Env/logs/run_20251021_143022.log
|
||
|
||
# 方式4：实时监控（适合长时间运行）
|
||
tail -f Env/logs/run_20251021_143022.log
|
||
```
|
||
|
||
---
|
||
|
||
### Q3: 日志文件太多怎么办？
|
||
|
||
**A**: 可以定期清理旧日志：
|
||
|
||
```bash
|
||
# 删除7天前的日志
|
||
find Env/logs/ -name "*.log" -mtime +7 -delete
|
||
|
||
# 只保留最新的10个日志
|
||
cd Env/logs && ls -t *.log | tail -n +11 | xargs rm -f
|
||
```
|
||
|
||
---
|
||
|
||
### Q4: 日志会影响性能吗？
|
||
|
||
**A**: 影响很小，因为：
|
||
1. 文件I/O是异步的
|
||
2. 使用了缓冲区
|
||
3. 立即刷新确保数据不丢失
|
||
|
||
如果追求极致性能，建议训练时不启用日志，只在需要分析时启用。
|
||
|
||
---
|
||
|
||
### Q5: 可以同时记录多个脚本的日志吗？
|
||
|
||
**A**: 可以，每个脚本使用不同的日志文件：
|
||
|
||
```bash
|
||
# 终端1
|
||
python Env/run_multiagent_env.py --log --log-file=script1.log
|
||
|
||
# 终端2（同时运行）
|
||
python Env/test_lane_filter.py --log --log-file=script2.log
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 最佳实践
|
||
|
||
### 1. 开发阶段
|
||
|
||
```bash
|
||
# 使用调试模式 + 日志，方便排查问题
|
||
python Env/test_lane_filter.py --debug --log
|
||
```
|
||
|
||
### 2. 长时间运行
|
||
|
||
```bash
|
||
# 启用日志，避免输出丢失
|
||
nohup python Env/run_multiagent_env.py --log > /dev/null 2>&1 &
|
||
|
||
# 查看实时输出
|
||
tail -f Env/logs/run_*.log
|
||
```
|
||
|
||
### 3. 批量实验
|
||
|
||
```bash
|
||
# 为每次实验使用不同的日志文件
|
||
for i in {1..5}; do
|
||
python Env/run_multiagent_env.py --log --log-file=exp_${i}.log
|
||
done
|
||
```
|
||
|
||
### 4. 性能测试
|
||
|
||
```bash
|
||
# 不启用日志，获得最佳性能
|
||
python Env/run_multiagent_env_fast.py
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 相关文档
|
||
|
||
- `README.md` - 项目总览
|
||
- `DEBUG_GUIDE.md` - 调试功能使用指南
|
||
- `CHANGELOG.md` - 更新日志
|
||
|
||
---
|
||
|
||
## 🔍 技术细节
|
||
|
||
### 实现原理
|
||
|
||
1. **TeeLogger类**：实现同时写入终端和文件
|
||
2. **上下文管理器**：自动管理资源（文件打开/关闭）
|
||
3. **sys.stdout重定向**：拦截所有print输出
|
||
4. **即时刷新**：每次写入后立即刷新，确保数据不丢失
|
||
|
||
### 源代码
|
||
|
||
详见 `Env/logger_utils.py`
|
||
|
||
```python
|
||
# 简化示例
|
||
class TeeLogger:
|
||
def write(self, message):
|
||
self.terminal.write(message) # 输出到终端
|
||
self.log_file.write(message) # 写入文件
|
||
self.log_file.flush() # 立即刷新
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 总结
|
||
|
||
- ✅ 简单易用：只需添加 `--log` 参数
|
||
- ✅ 不影响输出：终端仍可实时查看
|
||
- ✅ 自动管理：文件自动开启/关闭
|
||
- ✅ 灵活配置：支持自定义文件名和目录
|
||
- ✅ 完整记录：包含所有调试信息
|
||
|
||
立即开始使用：
|
||
|
||
```bash
|
||
python Env/test_lane_filter.py --debug --log
|
||
```
|
||
|