Debug a Cloud Run service in Cloud Code for VS Code

Cloud Code for VS Code lets you easily debug an application deployed to Cloud Run by leveraging skaffold debug. For detailed information about Skaffold debugging, see Debugging with Skaffold.

You don't need to complete manual setup like setting up port forwarding or injecting language-specific debug arguments. Debugging requires a Cloud Code-ready Cloud Run application that includes a skaffold.yaml configuration file and a launch.json file of type cloudcode.cloudrun.

Debug your Cloud Run service

To debug your service, follow these steps:

  1. To run your service and attach a debugger session to it, open the command palette (press Ctrl/Cmd+Shift+P or click View > Command Palette) and then run the Debug on Cloud Run Emulator command.

  2. In the Run/Debug on Cloud Run Emulator dialog, set the specifications for your configuration:

    • Choose Docker or Buildpacks as your builder and then specify your Dockerfile or Buildpack.
    • (Optional) To specify a Dockerfile target or build arguments, click Show Advanced Build Settings and then specify the target or arguments.
    • (Optional) To specify a custom service name, container image URL, container port, identity for the service to use, number of dedicated CPUs, or amount of memory to allocate to each container instance, click Show Advanced Service Settings and then specify the values.
    • (Optional) To specify any environment variables, click Show Advanced Service Settings, click Environment Variables, and then specify the values.
    • (Optional) To specify Cloud SQL connections, click Connections and then specify one connection per line.
    • (Optional) To have VS Code reestablish a debugging session after you save a change to your code, check the Automatically re-build and re-run on changes checkbox.

    If you want to further customize how your service is run, you can edit your launch.json file directly.

  3. To begin debugging your service, click Debug.

  4. If prompted, authenticate your credentials to run and debug an application locally.

  5. For each debuggable container in your service, confirm or enter the directory in the remote container where the program you'd like to debug is found.

    Alternatively, you can press ESC to skip debugging a container.

    Remote Root prompt

    Cloud Code attaches a debug session for each debuggable container in the service.

    By default, when you save a change to your application, Cloud Code redeploys your application and sets up a new debug session. You can toggle this feature with the watch flag in your project's launch configuration.

  6. To add a breakpoint, click in the editor margin of the file you're debugging.

    Red filled circles signify active breakpoints and gray hollow circles signify disabled breakpoints.

    For finer breakpoint control, you can use the Breakpoints section in VS Code's Debug view.

    Breakpoints section in the left hand panel of Debug View that allows adding, removing, and disabling breakpoints

    When you send a new request to your service, it pauses at the line you specified.

  7. After your session completes, right-click to use the following commands:

    • View Logs: Open the application logs of a specific deployment with the Cloud Code Logs Explorer
    • Open URL: Open the application service URL of a specific service in a web browser

  8. If you've turned off watch mode in your launch configuration and you want to make changes to your application and rebuild and redeploy the application, click the Cloud Code status bar and then click Turn on watch mode.

  9. If you want to inspect variables and stack info, use the Debug Sidebar. To interact with the debugging session, use the Debug Console in the bottom pane debugger.

  10. To stop your deployment, click the Stop button in the action bar for your current deployment.

    Action bar for Cloud Run deployment

Troubleshoot container-building issues

If you're getting the BUILD_DOCKER_UNKNOWN error code, this indicates a problem with Docker. To resolve this issue, perform one or more of the following tasks:

  • Restart Docker and try building the container again.

  • If you're still getting the same error after restarting, Docker could be running out of disk space. To learn more about cleaning up unused objects in Docker, see Prune unused Docker objects.

  • Try Docker's Disk Usage extension to help reclaim space.

Configuration details

Cloud Code handles the following language-specific configuration details:

Node.js

Rewriting the entrypoint to invoke:

node --inspect=localhost:9229

Python

Installing the ptvsd module using an Init Container and rewriting the entrypoint to invoke:

python -m ptvsd --host localhost --port 5678

Go

Installing the dlv debugger using an Init Container and rewriting the entrypoint such that the launched debug session runs with a debug server only (in headless mode), continues the debugged process on start, accepts multiple client connections, and listens at localhost:56268:

dlv exec --headless --continue --accept-multiclient --listen=localhost:56268 --api-version=2, <app> --

Java

Adding an environment JAVA_TOOLS_OPTIONS with the appropriate Java Debug Wire Protocol (JDWP) configuration such that the JDWP debugging agent listens for a socket connection on port 5005 and allows the VM to begin executing before the debugger is attached:

jdwp=transport=dt_socket,server=y,suspend=n,address=5005,quiet=y

.NET

.NET Core applications are configured to be deployed along with vsdbg for VS Code.

If you encounter problems with the automatic configuration, see Detailed debugger configuration and setup for help troubleshooting.

Get Support

To send feedback, report issues on GitHub, or ask a question on Stack Overflow.