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

怎样建立统一日志等级

怎样建立统一日志等级

统一日志等级不是给消息贴标签,而是让开发、测试和线上诊断对“严重程度”形成同一套判断。设计得当后,开发期能保留足够细节,线上又不会被大量无价值日志淹没,真正的异常也能被稳定检索和告警。

学习目标

  • 明确 Debug、Info、Warning、Error、Fatal 的使用边界
  • 用统一规则决定一条日志应该属于哪个等级
  • 通过最小实现验证等级过滤是否符合预期

先按“系统还能否正常继续”分级

最实用的判断顺序不是看文字听起来多严重,而是看事件对当前功能和进程的影响。只要团队始终按影响判断,同一类问题就不会有人写成 Info、有人又写成 Error。

等级 适合记录什么 典型边界
Debug 高频内部状态、临时诊断细节 不应默认长期全量开启在线上
Info 正常但有诊断价值的关键里程碑 不记录每帧、每次轮询等高频事件
Warning 出现异常,但已有降级、重试或兜底 当前流程仍能继续
Error 当前操作失败,需要调查 进程或会话仍可继续
Fatal 状态已不可安全恢复 通常意味着会话或进程即将终止

例如“资源第一次读取失败,但随后从备用地址加载成功”更适合 Warning;“本次资源加载最终失败,场景无法继续”应记为 Error;只有客户端已经进入不可恢复状态时,才使用 Fatal。

让等级同时控制输出范围

统一等级还必须配合过滤策略,否则只是换了五个标签。下面用一个最小 C# 程序演示:运行环境把最低等级设置为 Info 后,Debug 会被过滤,其余更高等级继续输出。

csharp
using System;

enum LogLevel
{
    Debug = 10,
    Info = 20,
    Warning = 30,
    Error = 40,
    Fatal = 50
}

static class Logger
{
    public static LogLevel MinimumLevel { get; set; } = LogLevel.Info;

    public static void Log(LogLevel level, string message)
    {
        // 统一在出口做等级过滤,避免各业务模块自行判断。
        if (level < MinimumLevel)
        {
            return;
        }

        Console.WriteLine($"[{level}] {message}");
    }
}

class Program
{
    static void Main()
    {
        Logger.MinimumLevel = LogLevel.Info;

        Logger.Log(LogLevel.Debug, "frame cache hit");
        Logger.Log(LogLevel.Info, "entered lobby");
        Logger.Log(LogLevel.Warning, "primary endpoint failed, fallback succeeded");
        Logger.Log(LogLevel.Error, "profile save failed");
        Logger.Log(LogLevel.Fatal, "runtime state corrupted, client must exit");
    }
}

预期输出:

text
[Info] entered lobby
[Warning] primary endpoint failed, fallback succeeded
[Error] profile save failed
[Fatal] runtime state corrupted, client must exit

真实项目可以把同样的判断放进 Unity、Unreal 或自研引擎的日志封装层,再把输出接到控制台、文件、远程日志或崩溃采集系统。关键不是复制这段代码,而是保证所有模块只通过同一个入口执行等级过滤。

给每个等级设可执行的团队规则

规则要能让不同开发者面对同一事件时做出接近的选择。最简单的方法是先问三个问题:这是正常路径吗;当前操作是否失败;失败后系统是否还能安全继续。

正常且值得追踪的关键节点写 Info;只为定位内部细节、且可能高频出现的内容写 Debug;发生偏差但被兜底成功写 Warning;本次操作已经失败写 Error;客户端无法安全继续时才写 Fatal。

日志等级之外还要统一事件名称、会话标识、构建版本和关键上下文字段。否则即使等级正确,线上出现一次 Error 时仍无法把前后的相关事件串起来。

控制噪声而不是简单“少打日志”

降低日志量不等于删除证据。优先处理重复且高频的信息,例如每帧状态、固定周期心跳成功、循环中的相同失败。它们更适合采样、聚合或仅在 Debug 模式下开启。

相反,进入关键场景、配置加载结果、网络重连开始与结束、资源回退、持久化失败等事件,即使发生频率不高,也应保留足以还原过程的 Info、Warning 或 Error。这样日志既不会失控,又能在故障发生后提供连续上下文。

最终标准很简单:看到一个等级时,工程师应能立刻判断“这是正常轨迹、已兜底异常、操作失败,还是不可恢复故障”,而不需要先猜作者当时的情绪。

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

目录与阅读设置

阅读设置

17

记录一个想法

怎样建立统一日志等级

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

登录哪都通