Plainnotes

结构化日志的字段,别随手起名

2025-07-09 · 3 分钟工具

把日志从文本改成 JSON,第一版通常长这样:{"time":"...","level":"info","msg":"...","data":{...}}。问题在后面:查询时发现一半服务叫 timestamp,一半叫 time;错误码有的在顶层,有的埋在 data 里。

建议先定几个约定:

  • 时间统一 ts,ISO 8601 带时区,UTC。
  • 级别 level,值限定 debug/info/warn/error。
  • 请求标识 request_id、trace_id,全链路透传。
  • 业务字段放平,别嵌套超过两层,否则查询语言很难写。
  • 错误用 err 对象,含 type、message、stack,别把堆栈拼进字符串。

字段名的稳定性比字段数量重要。多写几个字段不花钱,改名会让所有看板和历史查询一起失效。