日志格式设计：时间戳、模块名、线程ID、日志内容的标准格式规范
做嵌入式开发这么多年，我见过太多因为日志格式混乱而踩坑的案例。说白了，日志格式就是你和设备沟通的「语言」。语言不通，调试起来真要命。
今天咱们就聊聊，怎么设计一套靠谱的日志格式。我个人习惯把日志格式拆成四个核心字段：时间戳、模块名、线程ID、日志内容。别小看这四个字段，每个都有讲究。
时间戳：日志的灵魂
没有时间戳的日志，就像没有日期的日记——你根本不知道这事发生在什么时候。我在项目中遇到过最头疼的情况：设备跑了一周突然死机，日志里全是消息，但时间戳格式五花八门，根本没法串起来分析。
时间戳设计，我建议遵循这几个原则：
- 精度要够：嵌入式场景下，毫秒级是底线。有些实时性要求高的系统，甚至需要微秒级。
- 格式要统一：别今天用
2024-01-15 10:30:25.123，明天又改成2024/01/15 10:30:25.123456。统一用 ISO 8601 格式最省心。 - 时区要明确：如果设备会跨时区使用，建议统一用 UTC 时间，或者至少把时区信息带上。
推荐格式：YYYY-MM-DD HH:mm:ss.SSS
示例：2024-01-15 10:30:25.123
你想想看，如果日志里时间戳格式不统一，写脚本分析日志的时候得多痛苦？我曾经为了解析一个客户的日志，专门写了个格式自动识别模块——那感觉，就像在垃圾堆里找宝贝。
模块名：快速定位问题源头
模块名的作用，说白了就是告诉你「这事发生在哪个子系统里」。没有模块名，你看到一条日志还得猜：这是网络模块报的错，还是传感器模块报的错？
模块名设计，我有几个经验：
- 层级要清晰：比如
NET.TCP、SENSOR.TEMP，用点号分隔层级。 - 长度要控制：别搞太长的名字，比如
NETWORK_COMMUNICATION_TCP_IP_STACK，这太长了。建议不超过 16 个字符。 - 命名要一致：整个项目里，模块名不能有歧义。同一个模块，不能今天叫
NET，明天叫NETWORK。
| 模块 | 推荐命名 | 不推荐命名 |
|---|---|---|
| 网络通信 | NET | NETWORK_COMM |
| 温度传感器 | SENSOR.TEMP | TEMP_SENSOR_DRIVER |
| 文件系统 | FS | FILE_SYSTEM |
小技巧：可以在项目初期就定义好模块名列表，做成头文件。这样大家写代码时直接引用宏定义，不会乱起名字。
线程ID：多任务调试的利器
现在的嵌入式系统，动不动就跑个 RTOS，十几个线程同时跑。没有线程ID，你根本分不清这条日志是哪个线程打的。
我记得有一次调试一个死锁问题，日志里全是消息，但就是看不出哪个线程在等哪个线程。后来加上线程ID，一眼就发现了问题：线程A在等线程B释放锁，线程B却在等线程A释放锁——典型的死锁。
线程ID的设计要点：
- 用数字或短字符串：比如
TID:0x1234或者TID:MAIN。 - 要能映射到线程名：最好有个表，能查到
TID:0x1234对应的是SensorTask。 - 打印时固定宽度：比如
TID:0x1234统一用 6 位十六进制，方便对齐。
推荐格式：TID:0xXXXX
示例：TID:0x1234
日志内容：清晰、简洁、可解析
日志内容是最灵活的部分，但也是最容易乱的部分。我见过有人把日志内容写成散文，也见过有人写成天书。
日志内容设计，我建议遵循「三要三不要」：
- 要结构化：能用键值对就别用纯文本。比如
temp=25.3°C, humidity=60%比温度是25.3度，湿度是60%好解析。 - 要简洁：别写废话。比如
Error: sensor read failed就够了，别写成哎呀，传感器读取失败了，好难过啊。 - 要可解析：日志最终是要被脚本分析的。所以格式要固定，别今天用逗号分隔，明天用空格分隔。
- 不要带敏感信息：比如密码、密钥，千万别打出来。
- 不要用中文：嵌入式设备日志最好用英文，避免编码问题。
- 不要过长：单条日志建议不超过 256 字节，否则存储和传输都是负担。
完整格式示例
把上面四个字段组合起来，一个标准的日志格式长这样：
[2024-01-15 10:30:25.123] [NET.TCP] [TID:0x1234] Connection established, remote=192.168.1.100:8080
[2024-01-15 10:30:25.456] [SENSOR.TEMP] [TID:0x5678] Read failed, errno=5, retry=2
[2024-01-15 10:30:25.789] [FS] [TID:0x9ABC] File opened, path=/data/config.ini, size=1024嗯，这里要注意：方括号 [] 是字段分隔符，每个字段固定位置。这样写脚本解析的时候，直接按方括号切分就行，非常方便。
避坑指南
我曾经踩过的坑：
- 时间戳用了本地时间，结果设备跨时区后，日志时间全乱了。后来统一改成 UTC。
- 模块名用了中文，结果日志文件在 Windows 和 Linux 之间传来传去，编码全乱码了。
- 线程ID只打了数字，没有映射表。后来想查某个线程的行为，根本不知道哪个ID对应哪个线程。
为什么会这样？说白了，就是设计的时候没想清楚「这日志将来要怎么用」。你想想看，日志不只是给人看的，更是给脚本分析的。所以格式一定要固定、可解析。
知识体系总览
下面这张图，把日志格式设计的核心逻辑串起来了：
这张图把日志格式设计的四个核心字段和它们的关键要点都串起来了。你写代码的时候，照着这个结构来设计，基本不会出大问题。