How to debug Ruby on Rails in Heroku Staging with VSCode

We've set up a Heroku Ruby on Rails API app and used the Pipeline feature to create a Production and Staging copy of the app. We develop on a Linux VM with VSCode Remote from Windows PCs and push code via Git to Heroku. But sometimes code/settings that work on localhost on Dev don't work quite the same on Heroku, and sometimes that requires using the debugger on Heroku. We found examples on Heroku's website and others on how to do this for Node.js and Java apps, but nothing other than upping the LOG_LEVEL environment variable to DEBUG seemed to be available for Ruby on Rails.

We're interested in anyone else that has successfully remotely debugged a Ruby on Rails Heroku app with VSCode and want to know if you found any easier/better way to do it.

It turns out that several things were needed:

• Installing the Heroku CLI on your Dev VM so you can redirect your selected port to localhost.

• Adding the VSCode Extension VSCode rdbg Ruby Debugger by Koichi Sasada to your VSCode (currently v0.2.2 as of 9/10/2024)

• Including the debug gem in your Gemfile

  • gem 'debug'
    

• Adding a :staging to the :development group in the Gemfile where you included the debug gem so it's loaded in :development and :staging but not in :production

  • group :development, :staging do
        gem 'debug'
    end
    

• Adding 2 environment variables to your Heroku Staging Settings:

  • RUBY_DEBUG_OPEN

    • false means remote debugging is not available

    • true means the debugger on Heroku will start

  • RUBY_DEBUG_PORT

    • 9229 - we picked this port as we saw it in use in several articles relating to Node.js and other apps on Heroku - you can use any port high enough to not be in use and allowed for non-root access on Heroku in your slug

• Create and add entries to your launch.json in VSCode to allow for attaching to your app if running on localhost or if remote on Heroku Staging

  • {
         // Use IntelliSense to learn about possible attributes.
         // Hover to view descriptions of existing attributes.
         // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
         "version": "0.2.0",
         "configurations": [
    
    
    
             {
                 "type": "rdbg",
                 "name": "Debug current file with rdbg",
                 "request": "launch",
                 "script": "${file}",
                 "args": [],
                 "askParameters": true
             },
             {
                 "type": "rdbg",
                 "name": "Attach with rdbg: Run runrails -d first",
                 "request": "attach",
                 "showProtocolLog": true,
             }
             ,
             {
                 "type": "rdbg",
                 "name": "Attach with rdbg to HEROKU STAGING: Run heroku ps:forward 9229 --app your-staging-heroku-app-name-here",
                 "request": "attach",
                 "debugPort": "9229",
                 "localfsMap": "/app:${workspaceFolder}",
                 "showProtocolLog": true,
             }
         ]
    }
    

• Pushing code changes to your Heroku Staging app, restarting you Staging Dyno or just changing RUBY_DEBUG_OPEN from false to true (also does a restart)

• Redirecting Heroku port 9229 to your Dev localhost:9229

  • heroku ps:forward 9229 --app your-staging-heroku-app-name-here
Establishing credentials...done
SOCKSv5 proxy server started on port 1080
Listening on 9229 and forwarding to web.1:9229
Use CTRL+C to stop port fowarding

  • Note: misspelling of forwarding is from the Heroku CLI...

  • Note: you need to do this in a Linux terminal on your Dev machine (can be in VSCode), and stop/start it again every time you do a restart of your Heroku Staging app, as otherwise VSCode will timeout trying to connect to the previous version of your app that is no longer running

Once you've done the above, you can start VSCode debugging by pressing [F5], selecting the "Attach with rdbg to HEROKU STAGING..." choice in the VSCode debugger and starting a session.

Then access your Staging app via browser or program after setting breakpoints and have at it!