3. 日志数据模型：日志事件分类与字段定义

做运动控制这么多年，我越来越觉得日志系统就像系统的「黑匣子」。飞机有黑匣子，咱们的伺服驱动器、运动控制器也得有。今天咱们就来聊聊这个黑匣子里的数据该怎么组织。

3.1 日志事件分类：四个等级，各有各的用处

我个人习惯把日志分成四个等级。说白了，就是给每条消息贴个标签，告诉系统「这条消息有多重要」。

等级	名称	颜色标识	典型场景
0	错误 (ERROR)	红色	电机过流、编码器断线、急停触发
1	警告 (WARN)	黄色	温度偏高、位置偏差超限、通信丢包
2	信息 (INFO)	白色/绿色	启动完成、参数加载、模式切换
3	调试 (DEBUG)	灰色	PID计算中间值、轨迹插补点、寄存器读写

3.2 时间戳精度：微秒级是底线

运动控制讲究的是实时性。你想想看，一个伺服周期才100微秒，如果时间戳精度只有毫秒级，那日志基本就是废的。

我建议这样定：

• 现场总线日志：1微秒精度。EtherCAT的DC同步时钟能做到纳秒级，但日志记录1微秒就够了。
• 运动控制算法日志：10微秒精度。位置环、速度环的计算周期通常在这个量级。
• 系统状态日志：1毫秒精度。比如温度、电压这些变化慢的信号。

3.3 数据字段定义：一个日志事件长什么样？

嗯，这里要注意。字段定义不能太随意，也不能太死板。我总结了一套「最小必要字段」原则——每个字段都有它存在的理由。

// 日志事件结构体定义（C语言示例）
typedef struct {
    uint64_t    timestamp;      // 时间戳，微秒级绝对时间
    uint8_t     level;          // 日志等级：0-3
    uint8_t     source;         // 来源模块ID
    uint16_t    event_id;       // 事件ID，用于快速检索
    uint8_t     param_count;    // 参数个数（0-8）
    int32_t     params[8];      // 可变参数，用于携带数值
    char        msg[64];        // 可读消息字符串
} LogEvent_t;

字段说明：

• timestamp：64位微秒时间戳。别用32位，真的会溢出。
• level：0-3，对应上面说的四个等级。
• source：模块ID。比如0x01是电机驱动，0x02是轨迹规划，0x03是IO控制。
• event_id：事件ID。每个模块有自己的事件表，比如电机模块的0x01是「过流保护触发」。
• params：最多8个32位参数。比如过流时记录电流值、过压时记录电压值。
• msg：64字节的可读字符串。方便人眼查看，但别依赖它做自动化分析。

3.4 知识体系结构图

下面这张图是我画的数据模型整体结构。你可以看到日志事件从产生到存储的完整链路。

3.5 实战中的几个坑

讲完理论，我分享几个实际项目中踩过的坑。

坑一：日志等级滥用。 我见过有人把所有日志都打成ERROR级别。结果真正出问题时，根本分不清哪个是致命错误，哪个只是小警告。我的建议是：ERROR只留给「系统无法继续运行」的情况。

坑二：时间戳不同步。 多核系统里，每个核都有自己的计时器。如果不做同步，日志时间戳会乱成一锅粥。我在一个四轴联动项目里就吃过这个亏——排查问题时发现日志时间戳前后颠倒，查了三天才发现是核间时间不同步。

坑三：参数溢出。 params字段是int32_t，但有些传感器数据是uint32_t。直接赋值会导致符号位错误。我习惯在赋值前做一次类型转换检查。