游戏客户端架构 / 系统课时

日志字段该怎样统一设计

日志字段该怎样统一设计

结构化日志只有在字段长期稳定时才有价值。本课设计一套客户端通用字段,覆盖时间、级别、模块、线程、场景、会话与事件标识,并明确命名、类型和缺省规则,让不同模块产出的日志可以放在同一套查询条件下分析。

学习目标

  • 设计一组跨模块复用的客户端日志通用字段
  • 统一字段命名、数据类型和缺省值规则
  • 区分通用字段、业务字段与高基数字段

先固定所有模块都要遵守的字段

通用字段应该描述“这条事件处于什么运行上下文”,而不是塞入具体业务细节。推荐把基础字段控制在可长期维护的一组范围内:

字段 建议类型 含义
timestamp string 事件发生时间,统一时区与格式
level string debug、info、warn、error
module string 功能模块,如 network、shop
event string 稳定事件名,如 login_failed
thread string 线程或执行队列名称
scene string 当前游戏场景或页面
sessionId string 一次客户端会话标识
userId string 已登录用户标识,可为空
requestId string 网络请求或调用链标识,可为空

这些字段解决的是横向查询问题。比如先查 module=network,再限制 sessionId,就能看到一次会话中的网络事件,而不需要理解每个业务模块自己的文本格式。

命名规则要比字段数量更重要

字段名一旦进入日志平台、告警规则和查询脚本,修改成本会迅速放大。命名时应坚持三条规则:同一概念只有一个名字;同一字段保持同一类型;事件名使用稳定的机器可读值。

例如不要在不同模块同时出现 uid、user_id、playerId。如果团队统一为 userId,所有日志都使用这个名字。事件值也不要写成人类句子,推荐使用小写加下划线,如 resource_load_failed。

下面是一条符合统一规范的示例:

json
{"timestamp":"2026-10-08T03:20:15.123+08:00","level":"error","module":"network","event":"request_failed","thread":"io-2","scene":"battle","sessionId":"s-8f21","userId":"38291","requestId":"req-a91c","errorCode":"TIMEOUT","message":"match result request timed out"}

这类结构中,message 用于给人阅读,event 和其他字段用于机器过滤。不要把查询所需的信息只藏在 message 里。

业务字段应按事件追加

通用字段不应该试图覆盖所有业务。比如资源加载失败需要 assetPath,支付失败需要 orderId,网络失败需要 httpStatus。这些字段应跟随事件追加,而不是塞进全局固定字段集合。

可以把日志对象理解成“通用上下文 + 事件字段”:

json
{"timestamp":"<TIME>","level":"error","module":"asset","event":"asset_load_failed","thread":"main","scene":"lobby","sessionId":"<ID>","userId":"38291","assetPath":"ui/shop/icon_sword.png","errorCode":"NOT_FOUND"}

验证方法是在日志平台检查字段类型是否一致,并确认没有同义字段重复出现。<TIME> 和 <ID> 为运行时动态值。

预期结果:

text
userId    -> string
sessionId -> string
event     -> string
duplicate semantic fields -> 0

缺省值和敏感信息要提前定规则

可选字段缺失时,优先让字段不存在,或按日志平台约定写 null,不要在同一个字段中混用空字符串、"-"、"unknown"。否则聚合时会把同一种“无值”拆成多个类别。

同时要避免把令牌、密码、完整身份证号、支付凭据等敏感信息写入日志。即使某个值对排查有帮助,也应先考虑脱敏、哈希或只记录内部标识。

统一字段的最终目标不是让所有日志长得一模一样,而是让所有日志都能用同一组核心条件检索,再由具体事件补充必要业务字段。字段越稳定,后续搜索、聚合和告警就越可靠。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

日志字段该怎样统一设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通