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
Requires an existing copy of UDB 6.5 or later, or a free trial version (which the extension can
download and install automatically).
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
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.
Watch how to get started with Time Travel Debug for C/C++ with this YouTube
video. Or follow the instructions below.
- Time Travel / Reverse debugging.
- Launch, Attach, or Replay a LiveRecorder
- 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.
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
- 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
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
- 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:
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
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
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:
Use the ⊕ and ⊖ buttons,
Ctrl and mouse wheel, or a zoom gesture to zoom in on a particular period
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
the default pattern is
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
This extension provides three kinds of launch configuration:
Use one of these to start time-travel debugging your program with UDB.
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:
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).
Use this to pass command-line options to UDB. For example, add the following to tell UDB to
increase the size of its
"miDebuggerArgs": "--max-event-log-size 2G"
Refer to the
for the full list of UDB configuration options.
- When launching a program: If set to true, UDB stops at
- 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.
When UDB interprets or displays a wall-clock time that lacks a timezone, it uses the
You can specify a different timezone in your launch configuration, workspace settings, or user
For example, to set the default timezone in the launch configuration:
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
Environment variables to add to the environment for the program being
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.
Configuration settings when using UDB 6.8.0 or later. This must be an object
mapping configuration parameters to their values. Any documented environment
UNDO_ can be configured here. For example, to configure the
event log size and
number of snapshots:
You can also configure UDB by supplying command-line arguments via
and/or by exporting environment variables in a wrapper script and supplying
the path to the wrapper script via
For example, using a POSIX-compatible shell:
# Increase the size of UDB's event log to 2GB - see https://docs.undo.io/EventLog.html
exec udb "$@"
csh the equivalent command is
exec udb $*:q.
This property must be present to indicate that this is a UDB launch configuration.
Launch program or attach to a process using
Load and replay a recording made by Undo’s LiveRecorder.
You can find information about additional debugger properties on the
Visual Studio Code website.
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.
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
Refer to the
for limitations on the Undo Engine and UDB.
Please visit https://support.undo.io/ to submit a
support request and mention “VSCode” in the Subject line.
Contains artwork derived from Visual Studio Code -
Codicons, licensed under the Creative Commons
Attribution 4.0 International Public