Time Travel Debug for C/C++

The Time Travel Debug for C/C++ extension accelerates identifying bugs, finding their root causes in your code and fixing them.

Adds support for reverse debugging C/C++ applications running on Linux, with UDB time-travel debugger.

Requires an existing copy of UDB 6.5 or later, or download a free trial.

Animation

Time-travel through your code’s execution flow with full visibility and code-level observability into the state of your code at each step leading up to an error. Live debug and conduct effective root cause analysis without needing to predict ahead of time what to log, and avoiding disruptive redeployments.

With UDB you can:

View and analyze actual code execution behaviour.
Go back to any point in the debugger’s execution history.
Step backward and forward using individual instructions, source lines, function calls etc.
Regenerate the complete state of the program being debugged at any point in its execution; including information that is normally destroyed during execution.

Features

Time Travel / Reverse debugging.
Launch, Attach, or Replay a LiveRecorder recording.
Continue and Reverse Continue, stopping at Breakpoints/Conditional Breakpoints/Watchpoints.
Step In/Out/Over, and Reverse Step In/Out/Over.
Undo last navigation.
Visually navigate and zoom through the execution flow in the Timeline.
Jump to a Bookmark at any point in your program’s execution history.
Jump to any point in your program’s execution history where it printed a timestamp to a log.
Jump to the last or next point in your program’s execution history where the value of an expression changed.
Inspect global and local variable values at any point in your program’s execution history.
Evaluate expressions and call functions in the Debug Console at any point in your program’s execution history.

Getting started

Open your project workspace.

If you’re debugging remotely via the Remote - Containers, Remote - SSH or Remote - WSL extensions, install this extension in the Visual Studio Code window that is attached to the remote system.

From the main menu choose Run → Add Configuration and then choose either C++ (UDB) (which creates a default set of launch configurations) or C/C++ (UDB) Launch (which adds a UDB launch configuration to your existing set of launch configurations).

In either case, VS Code opens the launch.json file in the editor.

Specify the path to the executable that you’d like to debug as the program.
If UDB is not present on your path (i.e. the directory containing the udb executable is not listed in the $PATH environment variable) specify the path to the udb executable as miDebuggerPath. If you don’t have UDB you can download a free trial.

See below if you need to add UDB command-line flags, set environment variables etc.

Operation

To start debugging:

Select the Run icon in the Activity Bar on the side of VS Code.
Choose the (UDB) Launch configuration from the menu at the top left if it isn’t already active.
From the main menu choose Run → Start debugging.

Once you’ve started a time-travel debugging session you can use the buttons in the debugging control panel to navigate forwards and backwards through your program’s execution history:

Toolbar

Blue navigation buttons

The familiar Continue, Step Over, Step Into and Step Out buttons behave as you would expect, and you also have available Reverse Continue, Reverse Step Over, Reverse Step Into and Reverse Step Out buttons that perform the corresponding operations in reverse.
Green “Go To” buttons

Use the Go To Start and Go To End buttons to go to the start or end of your program’s execution history. Use the Go To Bookmark button to go a previously placed bookmark. Use the Go To Time button to go to a time in execution history, or a wall-clock time, for example a timestamp copied from a log file. Use the Last Changed button to go to the last time the value of an expression was modified.
Green “Undo” and “Redo” buttons

The Undo button undoes the operation of the last navigation or Go To button. Press this again to undo the previous operation, back to the start of your debugging session. The Redo button reverses the effect of the Undo button.
Yellow/Orange “Set Bookmark” button

The Set Bookmark button creates a bookmark at the current time in execution history. You can later return to this moment in time using the Go To Bookmark button, or by clicking on the bookmark in the Timeline. If you’re debugging a LiveRecorder recording bookmarks are persisted across debugging sessions on the same machine.

The TIMELINE section of the Run view shows the current position in the program’s execution history and the positions of bookmarks that you’ve placed with the “Set Bookmark” button.

You can also use the timeline to navigate:

Click on “start” and “end” to go to the start or end of your program’s execution history.
Click on a bookmark to return to that moment in time.

Use the ⊕ and ⊖ buttons, Ctrl and mouse wheel, or a zoom gesture to zoom in on a particular period of execution.

Log Jump

In the TERMINAL panel, and in open log files, timestamps that you can jump to are underlined. Control-click on a timestamp to jump to the corresponding time in recorded history. To configure which files are treated as log files containing wall-clock times, update the "udb.logFilePattern" setting in your workspace or user settings. This field is a glob pattern; the default pattern is "**/*.log".

To configure which log entries are recognized as containing bbcounts, update the "udb.bbcountRegex" setting in your workspace or user settings. The setting must be a regular expression with one capturing group containing the bbcount. The default is "bbcount[=: ]+([0-9,]+)".

Launch configurations

This extension provides three kinds of launch configuration:

(UDB) Launch

Use one of these to start time-travel debugging your program with UDB.
(UDB) Attach

Use this to attach to a running process and start time-travel debugging with UDB.
(UDB) Replay a LiveRecorder recording

Use this to load and replay a recording made by Undo’s LiveRecorder.

You can edit these configuration entries to customize UDB’s behaviour. Some notable options:

miDebuggerPath

The path to the udb executable. Leave this as "udb" if UDB is present on your path (i.e. the directory containing the udb executable is listed in the $PATH environment variable).
miDebuggerArgs

Use this to pass command-line options to UDB. For example, add the following to tell UDB to increase the size of its event log to 2GB:
```
"miDebuggerArgs": "--max-event-log-size 2G"
```
Refer to the Undo website for the full list of UDB configuration options.
stopAtEntry
- When launching a program: If set to true, UDB stops at main().
- When attaching to a process: This setting is ignored.
- When replaying a recording: If set to true, UDB stops at main() if the recording includes this. If set to false (the default) UDB stops at the end of the recording.
timezone

When UDB interprets or displays a wall-clock time that lacks a timezone, it uses the default timezone. You can specify a different timezone in your launch configuration, workspace settings, or user settings.

For example, to set the default timezone in the launch configuration:
```
"timezone": "Asia/Tokyo"
```
The timezone in the launch configuration overrides the default timezone in your workspace or user settings, if any. The workspace and user setting can be found in the UDB area in the Extensions section.
environment

Environment variables to add to the environment for the program being debugged.

Note that these environment variables are only applied to the program, not to UDB. To configure UDB's behaviour, use udbConfiguration or a wrapper script, as described below.
udbConfiguration

Configuration settings when using UDB 6.8.0 or later. This must be an object mapping configuration parameters to their values. Any documented environment variable starting UNDO_ can be configured here. For example, to configure the event log size and number of snapshots:
```
"udbConfiguration": {
    "UNDO_event_log_max": "2G",
    "UNDO_snapshots": 20,
}
```
You can also configure UDB by supplying command-line arguments via miDebuggerArgs, and/or by exporting environment variables in a wrapper script and supplying the path to the wrapper script via miDebuggerPath. For example, using a POSIX-compatible shell:
```
#!/bin/sh

# Increase the size of UDB's event log to 2GB - see https://docs.undo.io/EventLog.html
export UNDO_event_log_max=2G

exec udb "$@"
```
For csh the equivalent command is exec udb $*:q.
udb

This property must be present to indicate that this is a UDB launch configuration.
```
"udb": "live"
```
Launch program or attach to a process using udb.
```
"udb": "replay"
```
Load and replay a recording made by Undo’s LiveRecorder.

You can find information about additional debugger properties on the Visual Studio Code website.

Limitations

Multiple debug sessions

The extension doesn't support running a UDB debug session at the same time as another debug session, in the same instance of Visual Studio Code.

Data Watchpoints

The Visual Studio Code C/C++ extension doesn’t currently support setting data watchpoints from the Watch window (issue #1410). Open the Debug Console panel below the source code editor and type:

-exec watch <variable_name>

to set a data watchpoint on a variable, or

-exec watch -l <variable_name>

to set a data watchpoint on the memory location currently used to store the variable.

Then use the blue navigation buttons in the debugging control panel to run forwards or backwards until the variable’s value or memory location’s contents changes.

Refer to the GDB documentation for details of the watch command.

UDB

Refer to the Undo website for limitations on the Undo Engine and UDB.

Support

Please visit https://support.undo.io/ to submit a support request and mention “VSCode” in the Subject line.

Acknowledgements

Contains artwork derived from Visual Studio Code - Codicons, licensed under the Creative Commons Attribution 4.0 International Public License.