Logging

日志系统

框架为每个 Framework 组件、Mod、State 和 Mod Node 生成稳定的 ROS logger 身份。 Mod 不需要在清单中重复声明名称，身份直接来自已有的 Mod ID、State 名和 Node 名。

Logger 命名

<main-node>.fw.runtime
<main-node>.fw.scheduler
<main-node>.fw.state_machine
<main-node>.com.bxi.normal_depth
<main-node>.com.bxi.normal_depth.state.normal_depth
<main-node>.com.example.device.node.sensor_bridge

这些是真实的 ROS child logger 名称，可在终端和 /rosout 中识别，也可按 scope 设置 等级。外层 launch 仍可能显示 [bxi_example_py_elf3_demo-2]，那是 launch Action 的输出来源；内层 ROS logger 名称才是框架组件身份。

配置仍使用完整逻辑 scope：framework.* 和 mod.*。运行时只把显示名称缩短为 fw.*，并移除 mod. 前缀；不要把终端里看到的短名称原样复制到 logging.levels。

State 日志 API

Mod API 4.0 只保留一个状态日志入口：

class MyState(RobotControlState):
    def on_bind(self, ctx):
        self.logger.info("状态资源已绑定")

    def on_update(self, ctx, dt):
        if self.sensor_failed:
            self.logger.error("传感器不可用")

logger 在 on_bind() 之前由框架注入。不要使用 ctx.ros_node.get_logger() 记录状态 日志，否则会退回主节点身份。ctx.ros_node 只用于创建 subscription、publisher、 service 和 timer。

等级配置

logging:
  default_level: info
  levels:
    framework.scheduler: warning
    framework.state_machine: info
    mod.com.bxi.normal_depth: debug
    mod.com.example.device.node.sensor_bridge: info
  subprocess:
    max_line_bytes: 16384
    max_lines_per_sec: 200

levels 采用最长前缀匹配。上例的 mod.com.bxi.normal_depth 同时影响该 Mod 的 State 和 Node，除非后面再写更具体的 scope。支持 debug、info、warning、 error、fatal。

独立进程输出

Mod Node 的 stdout/stderr 由一个非控制线程统一排空，每行附加来源：

[com.example.device/sensor_bridge:out] Device ready
[com.example.device/sensor_bridge:err] Traceback (most recent call last):

这个机制对 Python、C/C++、ROS executable、普通 command 和厂商 SDK 一致。框架向 子进程注入 BXI_MOD_ID、BXI_NODE_ID、BXI_LOG_SCOPE 和 PYTHONUNBUFFERED=1。子进程无需理解这些变量。

max_line_bytes 防止无换行输出无限增长。max_lines_per_sec 是每个 Node、每条 stream 的独立限制；超额内容会被持续读取但不再写入终端，下一个窗口输出丢弃数量， 因此不会因 pipe 填满反向卡住子进程。

规则

• State 使用 self.logger。
• ROS Node 使用自己的 self.get_logger()。
• Framework 内部使用对应 framework.* logger。
• 只在 ROS logger 建立之前的 launch 检查、独立 CLI 工具和子进程原始输出中允许 print()。
• 不在 50 Hz 控制路径连续输出日志；持续信号使用统计或状态快照。