Time Traveling Debugger

This project is an attempt to build a usable, practical, useful and viable time-travel debugger.

A time-traveling debugger works by recording the each state in the execution of a program into a database - we call that the history file - and then allowing the programmer to navigate through this file to investigate the cause of bugs.

Subprojects

• Python Rewind - a modified version of Python (fork) that generates a log file as a program is executed. That log contains info that is needed to recreate the past states of the program.
• recreate - a C-based program (replacement for recreate.py) that reads the log file created by Python Rewind and generates the history of the program in a SQLite-based history file.
• timenav - a Python-based terminal UI debugger based on the SQLite-based history file. It also aims to be a use case for the debugger itself as the debugger will be developed with the help of the debugger itself - a case of dog-fooding.
• Oui - a terminal UI toolkit in Python
• history-api (deprecated) - a Node.js/Express-based REST API endpoint which returns a program's past states based on its SQLite-based history file. Debugger frontends are driven off this API.
• term-debugger (deprecated) - a terminal-based step debugger frontend written in Node.js and EcmaScript modules.
• zoom-debugger(deprecated) - a HTML5 Canvas-based ZUI debugger frontend written in TypeScript with Webpack as the bundler.
• json-like (deprecated) - a parser for a JSON-like data format with features specific to the time-traveling debugger, written in JavaScript.
• play-lang (deprecated) - a small programming language with built-in time-travel support. A program executed written in Play automatically generates a SQLite-based history file.
• rrui (deprecated) - a wrapper debugger around rr
• det-replay - a simple demonstrate of deterministic replay

Setup

This section is for developers who want to test out or modify the code. This has only been tested on OSX and Linux, apologies to Windows users. If you are on an unsupported platform and is interested in testing this out, let us know by submitting an issue.

1. Clone this repo and cd into the project directory.
2. . add-path - this will add the project's bin directory to your path.
3. Get Python Rewind via git submodule: get-python
4. Build Python Rewind:
   • cd cpython
   • ./configure
   • ./make
5. Now the command line tools below should be available.

Command-Line Tools

Once setup is complete, you are provided with a set of command-line tools:

1. pyrewind - used exactly like the python command, it invokes the modified version of Python with time-travel support if used with .py files. When you execute a .py file, a log file with the .rewind suffix is created. For example: pyrewind fib.py will generate a file called fib.rewind. Time-travel support is turned off when pyrewind is used as a REPL or used to execute a built-in module.
2. recreate - this program takes a .rewind file as input and generates a SQLite-based history file as output with the .sqlite suffix. For example: recreate fib.rewind will create a SQLite database called fib.sqlite. This database file can in turn by used to debug the originating program using one of the debugger frontends.
3. debug - starts the terminal-based step debugger. This command takes a .rewind log file or a history file as input. For example: debug fib.sqlite or debug fib.rewind. If the input is a .rewind log file, it will call the recreate command to convert it to a .sqlite file before launching the debugger. This debugger has a ncurses-style GUI and is controlled using one-stroke keyboard commands similar less and nano. It also supports mouse and scroll-wheel interactions for terminals that support it.
4. zoom - starts the zoom debugger (deprecated). This command also takes a history file as input. For example: zoom fib.sqlite. Running this command spawns a browser window within which the HTML5 canvas-based debugger executes.

Videos about the Time Traveling Debugger

I have been documenting work on the time-traveling debugger in video format. You can find all the videos in this playlist. Notable videos are:

• Time Travel Debugging (in Python)
• Dream of the Time Machine
• Introducing the Deep-Zoom Debugger (5 minutes)
• Deep Zoom Debugger Demo with Huiqi
• How Time-Traveling Works
• Time Traveling Debugger for Python
• rr and Record Replay Debuggers

Dependencies

This project is dependent on the following technologies:

• Node.js / Express
• Python 3
• SQLite
• better-sqlite3
• Nearley.js / Moo.js
• TypeScript
• HTML5 Canvas
• Webpack
• gcc / automake

Other Projects, Products and Papers on Time Travel Debugging

• Replay.io - time-travel debugger for JavaScript webapps based on Firefox. [Talk], [Reading].
• rr - time-travel debugger for C and C++. [Talk], [Paper].
• Timelapse - a time-travel debugger for JavaScript webapps based on Safari. [Video], [Reading], [Paper].
• ozcode - a replay debugger for .NET
• ODB (Omniscient Debugger) - an omniscient debugger for Java. [Talk], [Paper].
• Arnold an eidetic Linux-based system. [Paper]
• Paper: A Review of Reverse Debugging
• Sayid - Omniscient debugger for Clojure. [Video].
• Time Traveling in Microsoft WinDBG (Windows Debugger). [Video], [Talk].
• Time Traveling Debugger in Microsoft's Chakra JS Engine. [Talk], [Docs].
• Paper: Repeatable Reverse Engineering for the Greater Good with PANDA