Developers / Architects

Master Apex Replay Debugger: How to Streamline Debugging in Salesforce

By Tom Bassett

Within Salesforce, there are two main options for development – you can go with a clicks-not-code or with a code solution. What works best depends on your requirements and business processes. 

If you opt for code you’ll likely end up writing Apex which is debugged differently than clicks-not-code like Salesforce Flow. In this article, we will explore the Apex Replay Debugger and how it can help to debug. 

What Is the Apex Replay Debugger?

The Apex Replay Debugger is a tool that sits in Visual Studio Code. It’s part of the Salesforce Extension Pack, a collection of tools to enable programmatic development. It enables the playback of a debug session so you can see what happened line by line and monitor the values of variables too. It’s a free tool that doesn’t require additional licenses.

Screenshot from Apex Replay Debugger which shows the values from a Contact Record that's being created.

This differs from other tools such as Apex Interactive Debugger which in some cases is a paid add-on and offers live playback instead of offline playback of existing logs, like with the Apex Replay Debugger. 

You can also debug Apex using Debug Logs alone, but this may become troublesome when you need to understand the playback of an operation and how variables were set or changed. When using debug logs only, you may need to use System.debug to see what’s going on at key points.

Use Apex Replay Debugger 

Apex Replay Debugger uses Salesforce CLI, Visual Studio Code, and the Salesforce Extension Pack. Once you’ve set up the Salesforce Developer tools, got a local copy of Apex, and authorized your Salesforce Org, you can get debugging!

To get started, set up checkpoints and breakpoints in your code. A breakpoint is like hitting pause whereas a checkpoint provides more information for variables via a heap dump. 

In Visual Studio Code you can set a breakpoint within Apex by pressing to the left of the line number. If you want to set a checkpoint, highlight a line and then run SFDX:Toggle Checkpoint. Once you’ve set checkpoints don’t forget to then run SFDX: Update Checkpoints in Org!.  

GIF showing a Breakpoint being set on Line 5 of a Apex Class.

Once the breakpoints and checkpoints have been set up, run SFDX: Turn On Apex Debug Log for Replay Debugger. This turns on debugging for 30 minutes back within the Salesforce Org.

Now, you need to use SFDX: Run Apex Tests to run the Apex Test that you wish to debug. This will prompt you to choose either a specific test or all tests. Once this is complete you need to run SFDX: Get Apex Debug Logs and select the latest debug log from the list.

Now that you are within the Debug Log, this is where the magic happens. Right-click anywhere in the debug file and select SFDX: Launch Apex Replay Debugger with Current File. This will then bring up a control panel that looks like it belongs in a media player. Using this debug toolbar you can step between the breakpoints you set up earlier. 

Using these controls you can Continue, Step Over, Step Into, Step Out, Restart, or Stop the debugging session. During this process along the right-hand side you can view how variables develop during the run. 

In this example, I can see the relatedCase being inserted and the values within. This is particularly helpful when variables or values change, so at various points, you can check they are being correctly set. 

Considerations

As with everything in Salesforce, there are things to consider when using the Apex Replay Debugger. Depending on your specific use case you may be better off using an alternative tool or method to debug your code.

You can only replay one debug log at a time which makes it difficult to debug asynchronous Apex which produces multiple logs. Checkpoints expire after 30 minutes and heap dumps expire after about a day. 

You can’t replay logs generated by scheduled Apex and should the code error at any point the replay will end at that specific point. You can only use this tool to debug unmanaged code. 

Final Thoughts 

The reason why I wanted to write about this tool is that it’s helped me in the past to resolve issues without having to get a developer involved.

As a Solution Architect, I need to be able to understand and debug code and by stepping through code using this tool it helped me identify what was going wrong and how to fix it. Let us know in the comments what tool(s) you use to debug Apex Code!

Resources

The Author

Tom Bassett

Tom is a 31x Trailhead certified, 2x Slack certified, and an 11x accredited professional with over six years of experience in the Salesforce ecosystem.

Leave a Reply