Uni-Lab-OS/unilabos/utils/README_LOGGING.md

UniLabOS 日志配置说明

文件位置: unilabos/utils/log.py
最后更新: 2026-01-11
维护者: Uni-Lab-OS 开发团队

本文档说明 UniLabOS 日志系统中对第三方库和内部模块的日志级别配置，避免控制台被过多的 DEBUG 日志淹没。

---

📋 已屏蔽的日志

以下库/模块的日志已被设置为 WARNING 或 INFO 级别，不再显示 DEBUG 日志：

1. pymodbus（Modbus 通信库）

配置位置: log.py 第196-200行

# pymodbus 库的日志太详细，设置为 WARNING
logging.getLogger('pymodbus').setLevel(logging.WARNING)
logging.getLogger('pymodbus.logging').setLevel(logging.WARNING)
logging.getLogger('pymodbus.logging.base').setLevel(logging.WARNING)
logging.getLogger('pymodbus.logging.decoders').setLevel(logging.WARNING)

屏蔽原因:

• pymodbus 在 DEBUG 级别会输出每一次 Modbus 通信的详细信息
• 包括 Processing: 0x5 0x1e 0x0 0x0... 等原始数据
• 包括 decoded PDU function_code(3 sub -1) -> ReadHoldingRegistersResponse(...) 等解码信息
• 这些信息对日常使用价值不大，但会快速刷屏

典型被屏蔽的日志:

[DEBUG] Processing: 0x5 0x1e 0x0 0x0 0x0 0x7 0x1 0x3 0x4 0x0 0x0 0x0 0x0 [handleFrame:72] [pymodbus.logging.base]
[DEBUG] decoded PDU function_code(3 sub -1) -> ReadHoldingRegistersResponse(...) [decode:79] [pymodbus.logging.decoders]

---

2. websockets（WebSocket 库）

配置位置: log.py 第202-205行

# websockets 库的日志输出较多，设置为 WARNING
logging.getLogger('websockets').setLevel(logging.WARNING)
logging.getLogger('websockets.client').setLevel(logging.WARNING)
logging.getLogger('websockets.server').setLevel(logging.WARNING)

屏蔽原因:

• WebSocket 连接、断开、心跳等信息在 DEBUG 级别会频繁输出
• 对于长时间运行的服务，这些日志意义不大

---

3. ROS Host Node（设备状态更新）

配置位置: log.py 第207-208行

# ROS 节点的状态更新日志过于频繁，设置为 INFO
logging.getLogger('unilabos.ros.nodes.presets.host_node').setLevel(logging.INFO)

屏蔽原因:

• 设备状态更新（如手套箱压力）每隔几秒就会更新一次
• DEBUG 日志会记录每一次状态变化，导致日志刷屏
• 这些频繁的状态更新对调试价值不大

典型被屏蔽的日志:

[DEBUG] [/devices/host_node] Status updated: BatteryStation.data_glove_box_pressure = 4.229457855224609 [property_callback:666] [unilabos.ros.nodes.presets.host_node]

---

4. asyncio 和 urllib3

配置位置: log.py 第224-225行

logging.getLogger("asyncio").setLevel(logging.INFO)
logging.getLogger("urllib3").setLevel(logging.INFO)

屏蔽原因:

• asyncio: 异步 IO 的内部调试信息
• urllib3: HTTP 请求库的连接池、重试等详细信息

---

🔧 如何临时启用这些日志（调试用）

方法1: 修改 log.py（永久启用）

在 log.py 的 configure_logger() 函数中，将对应库的日志级别改为 logging.DEBUG:

# 临时启用 pymodbus 的 DEBUG 日志
logging.getLogger('pymodbus').setLevel(logging.DEBUG)
logging.getLogger('pymodbus.logging').setLevel(logging.DEBUG)
logging.getLogger('pymodbus.logging.base').setLevel(logging.DEBUG)
logging.getLogger('pymodbus.logging.decoders').setLevel(logging.DEBUG)

方法2: 在代码中临时启用（单次调试）

在需要调试的代码文件中添加：

import logging

# 临时启用 pymodbus DEBUG 日志
logging.getLogger('pymodbus').setLevel(logging.DEBUG)

# 你的 Modbus 调试代码
...

# 调试完成后恢复
logging.getLogger('pymodbus').setLevel(logging.WARNING)

方法3: 使用环境变量或配置文件（推荐）

未来可以考虑在启动参数中添加 --debug-modbus 等选项来动态控制。

---

📊 日志级别说明

级别	数值	用途	是否显示
TRACE	5	最详细的跟踪信息	✅
DEBUG	10	调试信息	✅
INFO	20	一般信息	✅
WARNING	30	警告信息	✅
ERROR	40	错误信息	✅
CRITICAL	50	严重错误	✅

当前配置:

• UniLabOS 自身代码: DEBUG 及以上全部显示
• pymodbus/websockets: WARNING 及以上显示（屏蔽 DEBUG/INFO）
• ROS host_node: INFO 及以上显示（屏蔽 DEBUG）

---

⚠️ 重要提示

修改生效时间

• 修改 log.py 后需要 重启 unilab 服务 才能生效
• 不需要重新安装或重新编译

调试 Modbus 通信问题

如果需要调试 Modbus 通信故障，应该：

1. 临时启用 pymodbus DEBUG 日志（方法2）
2. 复现问题
3. 查看详细的通信日志
4. 调试完成后记得恢复 WARNING 级别

调试设备状态问题

如果需要调试设备状态更新问题：

logging.getLogger('unilabos.ros.nodes.presets.host_node').setLevel(logging.DEBUG)

---

📝 维护记录

日期	修改内容	操作人
2026-01-11	初始创建，添加 pymodbus、websockets、ROS host_node 屏蔽	-
2026-01-07	添加 pymodbus 和 websockets 屏蔽（log-0107.py）	-

---

🔗 相关文件

• log.py - 日志配置主文件
• unilabos/devices/workstation/coin_cell_assembly/ - 使用 Modbus 的扣电工作站代码
• unilabos/ros/nodes/presets/host_node.py - ROS 主机节点代码

---

维护提示: 如果添加了新的第三方库或发现新的日志刷屏问题，请在此文档中记录并更新 log.py 配置。