先确定日志要回答的问题

假设设备出现一次通信超时。只有一句“接收失败”，很难知道失败发生在哪次请求、当前设备处于什么状态，以及系统后来做了什么。

设计日志时，可以先写出排查问题需要回答的三个问题：发生了什么？当时的上下文是什么？系统采取了什么动作？下面的记录是一种格式示例，字段和取值均用于说明。

t_ms=184230 level=WARN module=lidar
event=receive_timeout request_id=42
state=streaming elapsed_ms=120
action=retry attempt=1 max_attempts=3

优先记录状态变化

在资源有限的设备上，可以先梳理关键状态转换：初始化进入运行、连接中断、恢复完成、重试耗尽。每个状态转换都应能够说明原因和后续动作。

周期性的正常采样未必需要每次输出。需要观察趋势时，可以用计数、最大耗时或周期汇总表达；要复现一段算法输入时，则应考虑专门的数据记录机制。

让字段有稳定的含义

  • 时间：说明是单调时间还是墙上时间，并写清单位。
  • 事件：使用稳定名称，让相同问题能够被检索和聚合。
  • 关联：用请求或会话标识，连接一次操作中的多条日志。
  • 结果：区分等待重试、已经恢复与最终失败。

还需要对日志成本作出约束：缓冲区满时如何处理，哪些上下文允许阻塞，哪些数据不能直接记录。它们应成为日志接口的约定。

用一次故障回放检查日志

挑选一个具体故障，只看日志尝试还原过程。如果仍然必须猜测某个关键状态，就补足对应的记录；如果大量信息对判断没有帮助，就降低频率或移到调试级别。

日志的价值，最终体现在它能否帮助定位下一步。