MAGAIL4AutoDrive/Env/LOGGING_GUIDE.md

日志记录功能使用指南

📋 概述

为所有运行脚本添加了日志记录功能，可以将终端输出同时保存到文本文件，方便后续分析和问题排查。

---

🎯 功能特点

1. 双向输出：同时输出到终端和文件，不影响实时查看
2. 自动管理：使用上下文管理器，自动处理文件开启/关闭
3. 灵活配置：支持自定义文件名和日志目录
4. 时间戳命名：默认使用时间戳生成唯一文件名
5. 无缝集成：只需添加命令行参数，无需修改代码

---

🚀 快速使用

1. 基础用法

# 不启用日志（默认）
python Env/run_multiagent_env.py

# 启用日志记录
python Env/run_multiagent_env.py --log

# 或使用短选项
python Env/run_multiagent_env.py -l

2. 自定义文件名

# 使用自定义日志文件名
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. 组合使用调试和日志

# 测试脚本：调试模式 + 日志记录
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（标准运行脚本）

# 不启用日志
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（高性能版本）

# 启用日志
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（测试脚本）

# 标准测试 + 日志
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

---

💻 编程接口

如果您想在代码中直接使用日志功能：

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

---

🔧 高级配置

自定义日志目录

from logger_utils import setup_logger

# 指定不同的日志目录
with setup_logger(log_file="test.log", log_dir="my_logs"):
    print("日志会保存到 my_logs/test.log")

追加模式

from logger_utils import setup_logger

# 追加到现有文件（而不是覆盖）
with setup_logger(log_file="test.log", mode='a'):  # mode='a' 表示追加
    print("这条消息会追加到文件末尾")

只重定向特定输出

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

参数组合

# 示例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/ 目录下。如果目录不存在，会自动创建。

# 查看所有日志文件
ls -lh Env/logs/

# 查看最新的日志
ls -lt Env/logs/ | head -5

---

Q2: 如何查看日志内容？

A: 使用任何文本编辑器或命令行工具：

# 方式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: 可以定期清理旧日志：

# 删除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: 可以，每个脚本使用不同的日志文件：

# 终端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. 开发阶段

# 使用调试模式 + 日志，方便排查问题
python Env/test_lane_filter.py --debug --log

2. 长时间运行

# 启用日志，避免输出丢失
nohup python Env/run_multiagent_env.py --log > /dev/null 2>&1 &

# 查看实时输出
tail -f Env/logs/run_*.log

3. 批量实验

# 为每次实验使用不同的日志文件
for i in {1..5}; do
    python Env/run_multiagent_env.py --log --log-file=exp_${i}.log
done

4. 性能测试

# 不启用日志，获得最佳性能
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

# 简化示例
class TeeLogger:
    def write(self, message):
        self.terminal.write(message)  # 输出到终端
        self.log_file.write(message)  # 写入文件
        self.log_file.flush()         # 立即刷新

---

✅ 总结

• ✅ 简单易用：只需添加 --log 参数
• ✅ 不影响输出：终端仍可实时查看
• ✅ 自动管理：文件自动开启/关闭
• ✅ 灵活配置：支持自定义文件名和目录
• ✅ 完整记录：包含所有调试信息

立即开始使用：

python Env/test_lane_filter.py --debug --log