debugging-timelines

name	debugging-timelines
description	Investigate timeline divergence between head and base replays. Use when event sequences, ordering, or timing differ unexpectedly.

Debugging Timeline Divergence

Use this guide when replay timelines differ unexpectedly between head and base runs.

Investigation Steps

1. Load and Compare Timelines

• Read timeline.json from both head and base replay directories.
• The timeline is an array of events with timestamps, types, and data.
• Look for the first event where the timelines diverge.

2. Understand Event Types

Key timeline event types:

• user-event: User interactions (click, type, scroll, hover).
• network-request: API calls and responses.
• screenshot: Screenshot capture points.
• mutation: DOM mutations observed during replay.
• navigation: Page navigation events.
• error: JavaScript errors.
• console: Console log messages.

3. Identify Divergence Patterns

• Missing events: Events in base that don't appear in head (or vice versa).
• Reordered events: Same events but in different sequence.
• Timing shifts: Events at significantly different virtual timestamps.
• Extra events: New events not present in the baseline.

4. Check Timeline Stats

• Read timeline-stats.json for aggregated statistics.
• Compare event counts, durations, and error counts between replays.

5. Trace Back to Root Cause

• Once you find the divergence point, look at what happened immediately before.
• Check if a user event triggered different behavior.
• Look for conditional logic in the application that might execute differently.

6. Cross-Reference with Logs

• Use timestamps from the timeline divergence to find corresponding log entries.
• Check logs.deterministic.txt at the same virtual time for additional context.