游戏客户端架构 / 系统课时
线上日志怎样还原一次事件链
线上日志怎样还原一次事件链
战斗中一次攻击可能经过伤害结算、死亡判定、奖励发放和界面更新。线上出现奖励缺失或界面未刷新时,单看某条日志无法确定问题发生在哪里。本课通过关联 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。示例使用顺序执行来演示日志结构,不包含完整事件总线或并发调度实现。
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 时间戳,每行的时间值可能不同。
{"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 生成进程内序号,并交由线程安全的日志组件输出。
从日志定位事件链的断点
假设玩家报告敌人死亡后没有获得奖励,可以按照以下顺序检查:
- 根据战斗记录或请求上下文定位
correlationId,提取同一关联链的全部日志。 - 按
eventId归组,确认每个事件的发布记录、预期订阅者处理记录及处理结果。 - 根据
causationId将派生事件连接到父事件,形成实际发生的因果链。 - 找到最后一个成功处理的节点,检查其后续事件是否发布、是否入队,以及订阅者是否执行失败。
例如,EnemyDied 已发布且奖励订阅者报告处理成功,但找不到对应的 RewardGranted,问题很可能发生在奖励业务逻辑或奖励事件发布环节。
如果存在 RewardGranted 的发布记录,却没有 HUD 处理记录,则应进一步检查订阅关系、消息队列积压、对象生命周期以及处理异常。
需要注意,缺少日志不等于事件一定没有执行。日志丢失、采样、异步写入失败或采集链路中断,都可能造成类似现象。因此,关键处理节点应记录明确的成功或失败状态,必要时增加错误码、处理耗时和重试次数。
生产日志的可靠性边界
日志服务本身不能改变游戏业务结果。生产环境通常使用非阻塞的缓冲写入,避免每条高频事件都同步访问磁盘或网络。
以下几个边界需要特别处理:
- 高频事件:普通位置更新、动画状态变化等可以采样;死亡、奖励等关键业务事件应保留足够的诊断信息。
- 重复处理:一次事件可能因重试出现多条处理记录,应同时记录事件 ID、处理组件和尝试次数,不能把重复日志直接判断为重复业务事实。
- 异步执行:同一关联链可能分布在多个线程或进程中,应保留生产者标识和因果关系,不依赖全局时间排序。
- 隐私与安全:不在事件日志中写入认证令牌、完整个人资料或其他不必要的敏感数据。
- 日志丢失:关键业务正确性必须依靠状态、事务和幂等机制保证,不能依靠日志实现可靠投递。
真正能够还原事件链的日志,不只是记录事件发生过,而是保留事件身份、直接原因、处理节点和执行结果。当这些信息随事件一起传递时,即使故障跨越多个模块,也能沿着因果关系逐步缩小定位范围。