Chapter 29: Time-Travel Debugging and Execution Tracing

PMAT’s time-travel debugging capabilities allow you to record program execution, play back execution timelines, and compare different execution traces side-by-side. This powerful feature enables post-mortem debugging, regression analysis, and understanding complex execution flows.

What is Time-Travel Debugging?

Time-travel debugging records a complete execution trace of your program, capturing:

  • Variable states at each execution point
  • Stack frames and call hierarchy
  • Instruction pointers and memory snapshots
  • Timestamps for performance analysis

Once recorded, you can:

  • Replay execution forward and backward
  • Compare two execution traces to find divergence points
  • Analyze execution flow without re-running the program
  • Share execution recordings for collaborative debugging

Sprint 77 Features

PMAT’s time-travel debugging was developed through EXTREME TDD in Sprint 77:

  • TIMELINE-001: TimelinePlayer - Playback control for recordings
  • TIMELINE-002: TimelineUI - Terminal-based visualization
  • TIMELINE-003: ComparisonView - Side-by-side trace comparison
  • TIMELINE-004: CLI Integration - User-facing commands

Recording Format (.pmat)

Execution recordings are stored in .pmat files using MessagePack binary serialization:

#![allow(unused)]
fn main() {
struct Recording {
    metadata: RecordingMetadata,
    snapshots: Vec<Snapshot>,
}

struct Snapshot {
    frame_id: u64,
    timestamp_relative_ms: u32,
    variables: HashMap<String, serde_json::Value>,
    stack_frames: Vec<StackFrame>,
    instruction_pointer: u64,
    memory_snapshot: Option<Vec<u8>>,
}
}

Commands Overview

CommandPurposeUsage
pmat debug serveStart DAP server with recordingpmat debug serve --record-dir ./recordings
pmat debug replayReplay a recordingpmat debug replay recording.pmat
pmat debug timelineInteractive timeline playbackpmat debug timeline recording.pmat
pmat debug compareCompare two recordingspmat debug compare trace1.pmat trace2.pmat

Sections