3. 日志采集与预处理

在机器人功能冲突问题排查中，日志是重构故障现场的核心依据。若日志采集不规范、时间不同步或字段残缺，将直接导致原因定位寸步难行。本章围绕数据采集阶段，从关键字段定义开始，梳理主流采集工具与配置要点，重点解决时间同步与裁剪策略，确保日志数据可用、可对齐、可追溯。

3.1 现象识别：功能冲突中日志的常见异常

• 时间错位：同一冲突事件在不同模块日志中记录的时间戳相差数秒甚至数分钟，难以判断因果关系。
• 字段缺失：日志缺少模块名、线程ID或事件ID，无法将多个模块的日志串联成完整链路。
• 数据冗余：完整日志量级极大（如传感器流、运动控制循环日志），采集传输过程占满网络带宽或磁盘。
• 日志早于或晚于故障窗口：采集未裁剪，大量无关日志淹没关键信号，或时间同步失败导致日志归档延迟。

3.2 关键日志字段定义

问题排查型日志要求字段结构化、语义明确。以下为机器人系统强制推荐的日志字段及说明：

3.3 采集工具选型与对比

3.4 时间同步：保障日志时序的根本

所有机器人节点必须统一使用NTP或PTP进行时间同步。推荐 chrony（高精度、抗延迟抖动）。

检查清单（请逐项确认）

• 所有节点是否指向同一NTP服务器或时钟源？
• 是否启用 rtcsync 以避免系统重启后时间跳变？
• 日志中时间戳是否携带时区信息（ISO8601 + offsest）？
• 同步误差是否控制在100ms以内（机器人控制级别）？

chrony配置示例（/etc/chrony/chrony.conf）：

# 使用本地NTP服务器
pool ntp.company.local iburst
# 允许系统时钟漂移校正
makestep 1.0 3
rtcsync
# 日志统计
log statistics measurements tracking

验证同步状态：

chronyc sources -v
chronyc tracking

输出应显示 Last offset 绝对值小于0.1秒，Stratum 层级合理（通常2~3）。

3.5 日志裁剪：只关注故障窗口

原始日志量巨大，需在采集端或预处理阶段完成裁剪。常见策略：

Filebeat配置示例（采集时裁剪）：

filebeat.inputs:
- type: log
  paths:
    - /var/log/motion/*.log
  multiline.pattern: '^\d{4}-\d{2}-\d{2}'
  multiline.negate: true
  multiline.match: after
  # 仅转发时间为奇数的日志？此处做时间窗口裁剪：
  processors:
    - drop_event:
        when:
          range:
            "@timestamp":
              gte: "2026-02-18T14:28:00.000Z"
              lte: "2026-02-18T14:33:00.000Z"

3.6 修复动作：实施标准化采集与预处理

1. 统一日志格式：各模块使用结构化日志库（如Python logging + JSON formatter，或C++ spdlog with custom pattern）。
2. 配置时间同步：在系统部署脚本中安装chrony，写入局域NTP服务器地址，并启用rtcsync。
3. 部署采集代理：每个机器人节点部署Filebeat，配置文件包含多行合并规则和基础裁剪。
4. 验证字段完整性：用 grep 或 jq 检查日志是否包含所有必填字段。
5. 测试裁剪效果：模拟冲突事件，确认采集到的日志量是否在预期范围（如≤10MB/分钟）。

3.7 复测与验证

• 在机器人控制器上执行 chronyc tracking，确认 offset 小于50ms。
• 故意触发一次简单冲突（如同时写同一硬件资源），抓取采集到的日志，检查时间戳是否正确对齐。
• 使用 journalctl --since "1 min ago" --priority err 快速验证错误日志是否被完整捕获。

3.8 预防：持续保障日志质量

• 建立自动化检测：每晚定时检查所有节点时间同步偏差，偏差超200ms发告警。
• 日志量监控：若单节点日志速率超过预设阈值（如10MB/min），自动开启降级采样。
• 定期审计日志字段完整性：运行静态分析工具，扫描代码中日志输出是否缺少必填字段。
• 官方日志格式版本控制：升级模块时更新日志格式文档，并与采集配置同步。

3.9 日志采集与预处理全流程框架