摘要

  • qlog 允许系统时钟、单调时钟、相对纪元和相对前一事件等不同时间表达；同一端点的不同 trace 也不保证时间一致。
  • 客户端、服务器和网络观测点各自记录的是局部事实。没有捕获窗口、身份关联和时钟误差，局部先后不能升级为全局因果顺序。
  • 领导者应要求工具保留缺失与不确定性，并把协议日志同应用结果、对端证据和授权处置分开。

故障复盘会上，两条曲线看起来已经把答案说完了。客户端日志显示一次重传，服务器日志随后显示状态改变；图上的先后差只有几毫秒。于是报告写道：客户端重传触发了服务器异常。

两份文件都能解析。每份 trace 内的时间也都递增。问题是，客户端使用单调时钟，纪元未知；服务器使用系统时钟，在采集期间接受过校时；两边的采集开始点不同；用于关联连接的字段又经过了不同的匿名化处理。那几毫秒不是共同测得的因果间隔，而是分析平台把两套局部坐标投影到一张图后的视觉距离。

2026 年 7 月的 draft-ietf-quic-qlog-main-schema-14 正在 IETF QUIC 工作组推进，目标状态为 Proposed Standard，目前仍是 Internet-Draft，不是 RFC。它定义 qlog 的通用结构：文件、trace、事件、事件 schema、时间、观测点和序列化方式。对于 QUIC 这类线上数据被加密保护的协议，端点结构化日志可以提供外部抓包看不到的实现行为。统一格式也让不同实现和工具共享基本语义。

但统一语义并没有创造统一现实。qlog 规范的是“这条已记录事件如何解释”，不是“整个事故如何自动重建”。

每个观测点只拥有自己的方向

qlog 的 vantage_point 可以标明客户端、服务器、网络中间点或未知。网络观测点还可以说明流向采用客户端还是服务器语义，因为“发送”这个词必须相对于某个位置理解。出于隐私原因，能辅助判断方向的 IP 地址等信息可能不在日志里；方向也可能明确标成 unknown。

这项设计很重要。它阻止工具假装一个事件脱离位置仍有唯一含义。客户端的“packet sent”、服务器的“packet received”和中间点看到的线上数据，本可以互相支持，却不是天然同一条记录。它们的捕获窗口、丢失机制、标识符和时钟都不同。

tuple 字段同样是可选的。即使在连接迁移或多路径场景，实现也可以只在关键事件上记录 tuple。group_id 负责把事件归入逻辑组，但它不是普适的物理路径标识，更不是因果证明。缺失这些字段时，工具可以提出启发式匹配，却必须把匹配标成推断。

有序不等于同钟

每条 qlog 事件必须有数值时间，不过它表示从某个参考点起的时长。系统时钟可以向前或向后跳；单调时钟通常不会倒退，但它的 epoch 必须是 unknown。单调日志可附一个大致的墙上时间，草案明确提醒：不能据此安全地转换成日历时间。

时间格式也有两种基本选择。relative_to_epoch 让事件相对于参考纪元；relative_to_previous_event 让它相对于上一条已记录值。后者省空间，却把解释建立在保留下来的序列上。同一条 trace 里的事件甚至不必全部使用相同格式。

草案建议每条 trace 内按时间递增记录，同时承认多线程与流式记录器可能需要后处理排序。它进一步要求工具不要假定不同 trace 的时间戳相互一致，即使这些 trace 来自同一端点。

因此，“客户端 A 在本地早于客户端 B”“服务器 C 在本地晚于服务器 D”和“跨两端 A 导致 C”是三种证据等级。前两种可能由各自 trace 支持，第三种还需要共同身份、时钟误差范围、网络方向、采集覆盖和替代解释。把曲线画在一起只是分析动作，不会补齐这些条件。

缺失事件不会自动留下墓碑

时间合并还有一个更基础的前提：相关事件必须被保留。qlog 的 event_schemas 是对可能出现的命名空间和类型的提示，不是事件清单。列出 QUIC schema 并不保证所有相关类型都写入 trace。工具也不应因为出现未列出的类型或缺少已列 schema 的某个类型而报错。

Core、Base、Extra 的重要性分级也不是完整性级别。工具不应期待每条 trace 都包含所有 Core 事件。实现可以为了性能或隐私，以某些 Base 事件替代信息更丰富的 Core 事件。

更直接的是，固定大小的环形缓冲区可能让后来的记录覆盖连接建立阶段。隐私或文件大小政策也可以主动省略事件。草案要求工具面对不完整日志仍能给出适当输出，却没有要求每次覆盖或省略都生成逐事件墓碑。

于是两端 trace 即使各自连续，也可能覆盖不同的历史切片。客户端保留了握手、丢了尾部；服务器保留了故障尾部、丢了开头。将两条“连续线”拼成一条完整线，是界面做出的选择，不是日志提供的事实。

原因字段与相邻关系不是一回事

在高度并行的实现里，相关日志消息可能相隔很远。qlog 因此建议：如果具体事件需要表达触发原因，可以设置可选的 trigger 字段。显式 trigger 仍需结合事件定义理解，但它比“图上最靠近的另一条事件”更强。

缺少 trigger 时，专业做法是保留多个解释。包可能因内部错误、密钥不可用、重复、解析失败或策略拒绝而被丢弃；邻近的一次状态变化未必是原因。自动化系统若总用最近事件填空，会把调度与并发的偶然顺序训练成因果模型。

应用结果还在更后面。包被记录为发送，不等于对端收到；对端记录收到，不等于应用消费；连接状态结束，不等于用户请求完成。qlog 提供协议证据，服务结论仍须由应用指标、对端回执或独立观测支持。

为“可以合并”建立明确门槛

跨端时间线在合并前至少应保存：两边 logger 版本和配置；采集开始与结束回执；观测点与方向；时钟类型、参考时间、格式和误差；校时与进程重启；缓冲区覆盖计数；事件筛选与隐私政策；连接、tuple、group 和包级关联字段；导出与后处理步骤；以及无法匹配记录的数量。

随后，分析工具应输出区间而不是伪精确点。例如：“在服务器时间误差和客户端墙上时间近似的共同范围内，两个事件可能相差 -8 到 +17 毫秒，无法确定先后。”这样的结论看似不够果断，却准确说明了下一步需要什么：更可靠的时钟关联、同一包的共同标识，或新的受控试验。

这正是最小共同规范与本地决策之间应有的关系。qlog 让多家实现共享基本格式，同时允许它们根据成本和隐私选择捕获深度。本地自由不是让分析平台随意补故事，而是要求每个实现公开自己的证据边界。

来源