Two Clocks, One Agent Trace

Описание и применение

В трассировке агента смешиваются wall‑clock и монотонные таймстампы, что приводит к неверному порядку событий при смещении часов. Добавление счётчика seq и аудит скрипта позволяет корректно упорядочить события, сохраняя wall‑clock только для отображения.

Задача

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.

Источник