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".
Additionally, the official VS Code Python extension is needed to debug DBOS Python applications. For more information about this extension, please see the official VS Code documentation.
Local Replay Debugging
Once the DBOS Debugger extension is installed, VS Code will display a CodeLens
labeled 🔁 Replay Debug on every workflow function 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 dbos debug
command with the VS Code Python debugger attached.
From here, you can step through your DBOS workflow and inspect variables as you would when debugging any other Python application.
You can only step through workflow code when using the Replay Debugger. Step and transaction functions are skipped when Replay Debugging. The results returned from step and transaction functions when the workflow originally ran are retrieved and returned automatically without excecuting 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 functions.
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.
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.
