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

线上日志怎样还原一次事件链

线上日志怎样还原一次事件链

战斗中一次攻击可能经过伤害结算、死亡判定、奖励发放和界面更新。线上出现奖励缺失或界面未刷新时,单看某条日志无法确定问题发生在哪里。本课通过关联 ID、事件 ID、因果关系和时间戳设计结构化日志,让一次事件链能够被准确检索、拼接和分析。

学习目标

  • 区分关联 ID、事件 ID 和因果父事件 ID 的职责。
  • 为事件发布与订阅处理设计可检索的结构化日志。
  • 根据线上日志重建事件链,并识别缺失、失败和重复处理节点。

用三种标识建立事件关联

假设玩家攻击敌人后,客户端依次产生 AttackResolved、HealthChanged、EnemyDied 和 RewardGranted。如果每条日志只记录事件名称与时间,便无法判断这些事件是否属于同一次攻击。

需要为日志建立三个不同层级的标识。

字段 含义 使用规则
correlationId 一次业务操作的关联标识 同一事件链中的所有事件保持一致
eventId 单个事件实例的唯一标识 每次发布新事件时生成;多个订阅者处理同一事件时保持一致
causationId 直接导致当前事件产生的父事件 ID 派生事件填写父事件的 eventId;根事件可以为空

例如,攻击结果事件的 eventId 是 evt-001,伤害处理产生的生命值变化事件是 evt-002,那么后者的 causationId 应为 evt-001。如果生命值变化进一步触发死亡,死亡事件的父事件就是 evt-002,而不是最初的攻击事件。

这种设计同时提供两种查询方式:通过 correlationId 找到整条业务链,通过 causationId 还原每个事件的直接来源。

让日志覆盖发布和处理过程

事件链并不是一串简单的事件名称,还包含生产者、事件总线和订阅者之间的交互。

一条有诊断价值的事件日志,至少需要记录以下信息:

  • timestampUtc:UTC 时间戳,使用可解析的 ISO 8601 格式。
  • eventName:稳定的事件类型名称。
  • stage:当前操作阶段,例如 published、handled 或 failed。
  • component:执行当前操作的系统或订阅者。
  • sequence:当前进程内的日志序号,辅助判断实际记录顺序。

其中,时间戳用于分析延迟,序号用于区分同一进程内时间相近的记录,因果父 ID 则用于建立事件之间的逻辑关系。跨设备、跨进程场景不能依靠时间戳或某个进程的序号推导全局执行顺序。

战斗事件日志关联关系与因果链重建

图中的每个事件都有独立身份,但共用一个关联 ID。订阅者处理事件时保留原事件 ID;如果处理逻辑发布新事件,则为新事件生成 ID,并填写直接父事件 ID。

异步队列和后台任务尤其需要遵守这一规则。工作结果晚于原始请求返回时,也必须携带关联上下文,否则日志会被拆成无法关联的几段。

输出可检索的结构化日志

下面使用 .NET 8 控制台程序模拟一次战斗事件链。示例采用 JSON Lines 格式,每次日志调用输出一行独立 JSON,便于生产环境的日志采集器按字段过滤。

在 .NET 8 控制台项目中,将以下代码保存到 Program.cs,执行 dotnet run。示例使用顺序执行来演示日志结构,不包含完整事件总线或并发调度实现。

csharp
using System;
using System.Text.Json;

var correlationId = "battle-42";
var nextEventId = 0;
var nextSequence = 0;

void WriteLog(EventEnvelope e, string stage, string component)
{
    // 序号记录本进程内的日志顺序,不作为跨进程排序依据。
    Console.WriteLine(JsonSerializer.Serialize(new
    {
        timestampUtc = DateTimeOffset.UtcNow.ToString("O"),
        sequence = ++nextSequence,
        correlationId = e.CorrelationId,
        eventId = e.EventId,
        causationId = e.CausationId,
        eventName = e.Name,
        stage,
        component
    }));
}

EventEnvelope Publish(string name, EventEnvelope? cause, string component)
{
    // 新事件继承关联 ID,并记录直接触发它的父事件。
    var e = new EventEnvelope(
        cause?.CorrelationId ?? correlationId,
        $"evt-{++nextEventId:000}",
        cause?.EventId,
        name);

    WriteLog(e, "published", component);
    return e;
}

var attack = Publish("AttackResolved", null, "Combat");
WriteLog(attack, "handled", "Health");

var health = Publish("HealthChanged", attack, "Health");
WriteLog(health, "handled", "Death");

var death = Publish("EnemyDied", health, "Death");
WriteLog(death, "handled", "Reward");

var reward = Publish("RewardGranted", death, "Reward");
WriteLog(reward, "handled", "HUD");

record EventEnvelope(
    string CorrelationId,
    string EventId,
    string? CausationId,
    string Name);

预期输出如下,<TIME> 表示实际生成的 UTC 时间戳,每行的时间值可能不同。

text
{"timestampUtc":"<TIME>","sequence":1,"correlationId":"battle-42","eventId":"evt-001","causationId":null,"eventName":"AttackResolved","stage":"published","component":"Combat"}
{"timestampUtc":"<TIME>","sequence":2,"correlationId":"battle-42","eventId":"evt-001","causationId":null,"eventName":"AttackResolved","stage":"handled","component":"Health"}
{"timestampUtc":"<TIME>","sequence":3,"correlationId":"battle-42","eventId":"evt-002","causationId":"evt-001","eventName":"HealthChanged","stage":"published","component":"Health"}
{"timestampUtc":"<TIME>","sequence":4,"correlationId":"battle-42","eventId":"evt-002","causationId":"evt-001","eventName":"HealthChanged","stage":"handled","component":"Death"}
{"timestampUtc":"<TIME>","sequence":5,"correlationId":"battle-42","eventId":"evt-003","causationId":"evt-002","eventName":"EnemyDied","stage":"published","component":"Death"}
{"timestampUtc":"<TIME>","sequence":6,"correlationId":"battle-42","eventId":"evt-003","causationId":"evt-002","eventName":"EnemyDied","stage":"handled","component":"Reward"}
{"timestampUtc":"<TIME>","sequence":7,"correlationId":"battle-42","eventId":"evt-004","causationId":"evt-003","eventName":"RewardGranted","stage":"published","component":"Reward"}
{"timestampUtc":"<TIME>","sequence":8,"correlationId":"battle-42","eventId":"evt-004","causationId":"evt-003","eventName":"RewardGranted","stage":"handled","component":"HUD"}

示例中的事件编号和关联 ID 为便于观察而使用固定格式。正式系统应生成在所需作用域内唯一的事件 ID,并将关联上下文作为不可随意修改的数据与事件一起传递。

如果事件总线允许并发发布,计数器和日志写入必须改为线程安全实现,例如使用 Interlocked.Increment 生成进程内序号,并交由线程安全的日志组件输出。

从日志定位事件链的断点

假设玩家报告敌人死亡后没有获得奖励,可以按照以下顺序检查:

  1. 根据战斗记录或请求上下文定位 correlationId,提取同一关联链的全部日志。
  2. 按 eventId 归组,确认每个事件的发布记录、预期订阅者处理记录及处理结果。
  3. 根据 causationId 将派生事件连接到父事件,形成实际发生的因果链。
  4. 找到最后一个成功处理的节点,检查其后续事件是否发布、是否入队,以及订阅者是否执行失败。

例如,EnemyDied 已发布且奖励订阅者报告处理成功,但找不到对应的 RewardGranted,问题很可能发生在奖励业务逻辑或奖励事件发布环节。

如果存在 RewardGranted 的发布记录,却没有 HUD 处理记录,则应进一步检查订阅关系、消息队列积压、对象生命周期以及处理异常。

需要注意,缺少日志不等于事件一定没有执行。日志丢失、采样、异步写入失败或采集链路中断,都可能造成类似现象。因此,关键处理节点应记录明确的成功或失败状态,必要时增加错误码、处理耗时和重试次数。

生产日志的可靠性边界

日志服务本身不能改变游戏业务结果。生产环境通常使用非阻塞的缓冲写入,避免每条高频事件都同步访问磁盘或网络。

以下几个边界需要特别处理:

  • 高频事件:普通位置更新、动画状态变化等可以采样;死亡、奖励等关键业务事件应保留足够的诊断信息。
  • 重复处理:一次事件可能因重试出现多条处理记录,应同时记录事件 ID、处理组件和尝试次数,不能把重复日志直接判断为重复业务事实。
  • 异步执行:同一关联链可能分布在多个线程或进程中,应保留生产者标识和因果关系,不依赖全局时间排序。
  • 隐私与安全:不在事件日志中写入认证令牌、完整个人资料或其他不必要的敏感数据。
  • 日志丢失:关键业务正确性必须依靠状态、事务和幂等机制保证,不能依靠日志实现可靠投递。

真正能够还原事件链的日志,不只是记录事件发生过,而是保留事件身份、直接原因、处理节点和执行结果。当这些信息随事件一起传递时,即使故障跨越多个模块,也能沿着因果关系逐步缩小定位范围。

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

目录与阅读设置

阅读设置

17

记录一个想法

线上日志怎样还原一次事件链

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

登录哪都通