Get Started with Time Travel Debug for VS Code

  • 14 October 2021
  • 4 replies
Get Started with Time Travel Debug for VS Code
  • Community Manager
  • 0 replies

So you already use Visual Studio Code and now let's get you set up and ready to time travel through your C/C++ code!


To get started, you’ll need:

  1. C/C++ for Visual Studio Code 1.1.3 or later.

  2. The Time Travel Debug C/C++ extension download here.

  3. a copy of UDB 6.5 or later (trial/ full) if you don’t already. A trial version is fine so grab your trial.

  4. a program to be debugged running on a supported Linux distro.

Make sure you take a quick look at the requirements listed below.


Quick start guide

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

  2. 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).

  3. 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

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


How to use

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:

  • Blue navigation buttons

    The familiar ContinueStep OverStep Into and Step Out buttons behave as you would expect, and you also have available Reverse ContinueReverse Step OverReverse Step Into and Reverse Step Out buttons that perform the corresponding operations in reverse.

  • Green “Goto” buttons

    You can use these to go to the start or end of your program’s execution history, to a previously placed bookmark, or to a wall-clock time - for example a timestamp copied from a log file.

  • “Undo” button

    Undoes the operation of the last navigation or goto button. Press this again to undo the previous operation, back to the start of your debugging session.

  • Red “Set Bookmark” button

    Creates a bookmark at the current time in execution history. You can later return to this moment in time using the Goto 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.


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.

  • udb

    This property must be present and set to true to indicate that this is a UDB launch configuration.

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



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.

4 replies

Hi Zoe,

I’m trying to run udb on a remote (Linux) session from vscode on Windows.
My issue is related to a “complex environment” I need to setup before running the application to debug:

  • not only some few variables I may set with vscode with “environment” variable
  • but a more complex environment that requires to call a csh script

Usually with vscode and udb or gdb, I can cope with this by setting:

"miDebuggerPath": "myscript.csh",


And in myscript.csh:

#! /bin/csh -f
### setup the complex environment ...
source anothescript.csh
### call udb with all parameters from script:
/udb_path/udb $*
This runs ok with vscode and any gdb/udb version including 6.3 and 6.5.1
But if want to get the new interface in .vscode/launch.json:
            "udb": true,
Then I have some “Licence checking” issues in vscode side:

“UDB: Please accept the license to continue.”

I accept (click accept button) and then an other error message:

“udb is not licensed - udb path: myscript.csh”

Is there a way to avoid this ?

Best Regards,


And in myscript.csh:

#! /bin/csh -f
### setup the complex environment ...
source anothescript.csh
### call udb with all parameters from script:
/udb_path/udb $*
You need to update your script to properly pass quoted arguments as there are some spaced commands being passed to udb…  Change the last line to :
exec /udb_path/udb $*:q


### call udb with all parameters from script:

/udb_path/udb $*


The last line of the wrapper script needs to be something like

exec /udb_path/udb "$@"

so that arguments containing spaces and other shell meta-characters are passed to UDB correctly.

This advice is from the Time Travel Debug documentation (search for “wrapper script”).

Than you for your replies !

For csh the syntax is Jason one, thanks !