Two Clocks, One Agent Trace

说明与用途

代理跟踪混合使用墙钟和单调时钟，导致时钟漂移时事件顺序错误。通过添加每进程 seq 计数器和审计脚本，可获得正确顺序，同时保留墙钟用于显示。

问题

Agent traces mix wall‑clock and monotonic timestamps, causing misleading ordering when clocks drift, suspend, or migrate.

结果

Traces become auditable; ordering is derived from monotonic sequence, not wall‑clock, eliminating false positives caused by clock drift.

工作流

• 1. Record each span as a JSONL line with span_id, parent_id, tool, seq, wall_start_ns, wall_end_ns, mono_start_ns, mono_end_ns.
• 2. Increment seq in the process that opens the span; it survives clock events.
• 3. Run clock_audit.py to read spans, check monotonic duration, drift tolerance, and child window containment.
• 4. Generate a report and reconstructed order for debugging.
• 5. Use wall‑clock only for display after audit.

证据

A single NTP step of two seconds is enough to invert the completion order of two tool calls, and from that moment your timeline viewer is rendering fiction.

来源

The fix is not to throw away wall clock. Humans need it, log correlation needs it, and your incident timeline needs it.

来源

Keep the record boring and explicit. One span per JSONL line, with a parent link, a per-process sequence counter, and both clocks sampled at the same two points in the span's life.

来源

The script below is standard library only, reads JSONL, and emits a report plus a reconstructed order.

来源