Skip to main content

Time Travel Debugger

The DBOS Time Travel Debugger VS Code extension enables you to debug your production application deployed on DBOS Cloud.

Installation

For VS Code setup instructions, please see Microsoft's official documentation.

The DBOS Time Travel Debugger Extension can be installed via the VS Code Marketplace website or by searching the VS Code Extension Marketplace for "DBOS".

Views

As of v1.2 of the DBOS Time Travel Debugger Extension, you can view your DBOS Cloud applications and database instances directly inside VSCode. Hovering over a cloud resource provides additional information in a tooltip.

DBOS Cloud resources

Launch Debug Proxy

The time travel debugger relies on Debug Proxy utility to project the state of the database as it existed when a selected workflow started. When debugging a DBOS application in VSCode, the Debug Proxy is launched automatically. You can launch the Debug Proxy manually in order to use psql for running interactive time-traveled queries.

When the Debug Proxy is running, its output appears in a VSCode terminal window. You cannot interact with the Debug Proxy via this window, but you can shut it down with Ctrl-C.

Launch DBOS Dashboard

This menu item launches the Monitoring Dashboard in a new browser instance.

Interactive Time Travel Commands

When interactively querying your DBOS Cloud database, the following additional commands can be invoked from the psql command prompt. As is typical for SQL commands, the interactive time travel commands are case insensitive.

DBOS TIMESTAMP

info

Can be shortened to DBOS TS

Sets the time travel debugger to a specific point in time for time travel queries. The timestamp can be specified in RFC 3339 format (example: 2024-04-22T14:56:56-07:00) or as an integer indicating the Unix epoch in milliseconds. RFC 3339 formatted timestamps must be enclosed in quotes.

Examples:

  • DBOS TIMESTAMP "2024-04-22T14:56:56-07:00";
  • DBOS TS "2024-04-22T14:56:56-07:00";
  • DBOS TIMESTAMP 1234567890;

DBOS WORKFLOW

info

Can be shortened to DBOS WF

Sets the time travel debugger to the specific point in time when a specified workflow started. Workflows are identified by their workflow UUID, which can be found in the Monitoring Dashboard. The workflow UUID must be enclosed in quotes when using this command.

Examples:

  • DBOS WORKFLOW "7eb0968a-fbf0-4af2-909f-51d8516e7351";
  • DBOS WF "7eb0968a-fbf0-4af2-909f-51d8516e7351";

DBOS SNAPSHOT RESET

Resets the time travel snapshot to the current time. Example:

  • DBOS SNAPSHOT RESET;

VSCode Commands

These commands can be invoked via the VS Code Command Palette.

DBOS: Log into DBOS Cloud

The time travel debugger needs information about the application and its database from DBOS cloud. While this information can be provided via configuration settings described below, the extension can retrieve this information via the DBOS Cloud CLI. This command runs dbos-cloud login on your behalf from inside VS Code.

Typically, the time travel debugger will automatically prompt you to login to DBOS cloud if you're not logged in or your credentials have expired. However, this command can also be executed explicitly.

DBOS: Delete Stored Passwords

note

This command was originally named "Delete Stored Application Database Passwords"

The time travel debugger needs your DBOS Cloud credentials as well as DBOS database password in order to access your database history. The extension will prompt the user to login to DBOS Cloud and for the DBOS database password when needed. Credentials are saved in VS Code's secrets storage so you don't have to enter it every time you use the time travel debugger. This command deletes any stored passwords saved in VS Code's secrets storage.

note

The database password is different from the DBOS Cloud login credentials. Please see Cloud Database Management for more information.

DBOS: Shutdown Debug Proxy

The time travel debugger relies on Debug Proxy utility to project the state of the database as it existed when a selected workflow started. The extension automatically launches the Debug Proxy the first time a DBOS application is time travel debugged. The debug proxy process is automatically shut down when VS Code shuts down, but this command can be used to shut down the debug proxy process manually.

Command Variables

VS Code supports using extension commands as variables in launch and task configuration files. The following commands are designed to be used as configuration file variables.

The default DBOS launch configuration includes both of these commands in the Time Travel Debug configuration.

{
"type": "node-terminal",
"request": "launch",
"name": "Time Travel Debug",
"command": "npx dbos debug -x ${command:dbos-ttdbg.get-proxy-url} -u ${command:dbos-ttdbg.pick-workflow-id}",
"preLaunchTask": "npm: build"
}

dbos-ttdbg.get-proxy-url

This command retrieves the url of the Debug Proxy. By default, this is http://localhost:2345, but the port can be configured via the 'debug_proxy_port' setting.

dbos-ttdbg.pick-workflow-id

This command prompts the user to choose a select a workflow to debug. For more information, please see the Time Travel Debugger tutorial.

Configuration

Some behavior of the extension can be controlled via VS Code Settings.

dbos-ttdbg.debug_proxy_port

The Debug Proxy listens on port 2345 by default. This port can be changed via the dbos-ttdbg.debug_proxy_port configuration setting.

dbos-ttdbg.debug_pre_launch_task

By default, the Time Travel Debugging CodeLens will use the settings from the first VS Code launch configuration that includes dbos-cloud debug in the command string. If there are no such launch configurations, the extension will create a launch configuration from scratch. The dbos-ttdbg.debug_pre_launch_task configuration setting is used as the preLaunchTask value of the generated launch configuration.

warning

This configuration setting is ignored if you have a launch configuration with dbos-cloud debug in the command string, even if that launch configuration does not specify a preLaunchTask.

DBOS Cloud Database Connection

Typically, the time travel debugger retrieves database connection information via DBOS Cloud CLI. However, the developer can specify this information directly via VS Code settings, bypassing the need to use DBOS Cloud CLI.

note

For security reasons, the database password cannot be specified via VS Code settings.