Debugging
DBOS applications automatically save their state to Postgres every time a workflow step is executed. While this is primarily done for reliablity and fault-tolerance, the saved state can also be used for debugging purposes. The DBOS Debugger enables you to replay the execution of your application workflows, step through the recorded states and identify the root cause of bugs more efficiently.
Preliminaries
The DBOS Debugger is an extension to Visual Studio Code (aka VS Code), a free cross-platform interactive development environment. If you don't already have VS Code installed, please see their official documentation to get started.
The DBOS Debugger can be installed from the VS Code Marketplace website or or by searching the Extension Marketplace inside VS Code for "DBOS".
Local Replay Debugging
Once the DBOS Debugger extension is installed, VS Code will display a CodeLens
labeled 🔁 Replay Debug on every workflow method in your application.
If you click on the Replay Debug CodeLens, a list of recent workflow IDs will be shown. You can filter the list of workflow IDs by entering a value in the text box above the list. If the workflow you wish to debug does not appear in the list, select the pencil icon in the upper right hand corner of the picker window to manually enter a workflow ID.
After selecting a workflow ID, the DBOS debugger will automatically launch your application with the npx dbos debug
command with the VS Code TypeScript debugger attached.
From here, you can step through your DBOS workflow and inspect variables as you would when debugging any other TypeScript application.
You can only step through workflow code when using the Replay Debugger. Step and transaction methods are skipped when Replay Debugging. The results returned from step and transaction methods when the workflow originally ran are retrieved and returned automatically without executing the function body.
Cloud Replay Debugging
You can also replay debug DBOS applications deployed to DBOS Cloud.
If your application is deployed to DBOS Cloud and you are logged into DBOS Cloud in the DBOS Debugger, you will see an additional
☁️ Cloud Replay Debug CodeLens attached to your DBOS workflow methods.
Cloud replay debugging works the same as local replay debugging.
The only difference is the database your application connects to.
When cloud replay debugging, the DBOS Debugger retrieves the DBOS Cloud database connection information
and passes it to the dbos debug command via environment variables,
overriding the database connection information in the dbos-config.yaml file.
Time Travel Debugging
If your DBOS Cloud application was deployed with time-travel enabled,
you will also see a ⏳ Time-Travel Debug CodeLens attached to your DBOS Workflow methods.
Unlike replay debugging, Time Travel debugging does not step over transaction methods.
DBOS Console Integration
When using the cloud replay or time travel debuggers, an additional button appears in the upper right corner of the pick list next to the pencil icon. This button launches your default browser and navigates to the DBOS Cloud Workflow Manager page.
In the DBOS Cloud Workflow Manager, a new control button appears that allows you to select the workflow that you wish to debug. Selecting the debug button in this view will navigate the user back to VS Code, where the debugger will launch the selected workflow.
For your safety, VS Code will ask for confirmation before navigating to the Workflow Manager page and when navigating back to VS Code. If desired, you can configure VS Code not to prompt on these navigation events in the future.
Log Into to DBOS Cloud
To login to DBOS Cloud in the DBOS Debugger, navigate to the DBOS Cloud view and select the Log Into DBOS Cloud menu item.
Alternatively, you can open the VS Code Command Palette
and run the DBOS: Log Into DBOS Cloud command directly.
