Setting Up Stackdriver Debugger for Go applications

You can use Stackdriver Debugger with any Go application running on a Google Compute Engine instance. We recommend that you enable it on all running instances of your application.


  • You must be using Compute Engine VM instances running 64-bit Debian Linux images.

    To create a Compute Engine instance, see Creating and Starting an Instance.

  • To use Stackdriver Debugger, your Compute Engine VM instance must be created with one of the following access scopes:

    • (or, Allow full access to all Cloud APIs)

Building your application

Beta release restrictions

The current Go compiler's optimizations interfere with accurate debugging. As a result, Stackdriver Debugger shows incorrect information about your application when your application is built with the default Go compiler optimizations.

Turning off optimizations

To get the correct debugging information, build your application without the default optimizations. The following sample commands demonstrate how to disable optimizations:

go build -gcflags='-N -l'

The preceding gcflags value includes an uppercase letter N and a lowercase letter L.

Generate the source context file

The source context file contains information about the version of the source code used to build your application. The Debug page in the GCP Console uses this information to display the correct version of the source.

To generate the source context file, commit any outstanding changes and sync with your remote repository, then run the following in the root directory of your local Git repository.

gcloud debug source gen-repo-info-file [--output-directory <dir>]

Then, deploy (or redeploy) your application to your Compute Engine instance, including the source-context.json file.

Download the agent

The Stackdriver Debugger agent is a light-weight binary that you enable for your application at startup. The agent starts with your application and communicates with the Stackdriver Debugger backend while the application is running.

Once you've built and deployed your Compute Engine application, download the pre-built agent executable:

wget -O go-cloud-debug
chmod 0755 go-cloud-debug

Then, start the agent and your program with:

./go-cloud-debug -sourcecontext=PATH_TO_FILE -appmodule=APP_NAME -appversion=APP_VERSION -- PROGRAM_NAME arg1 arg2


  • PROGRAM_NAME specifies the relative path to your application binary.

  • -sourcecontext specifies the path to the JSON-formatted file containing your source context configuration. See Generate the source context file for information on generating this file.

  • -appmodule is the name of your application or service. This, along with the version, is used to identify your application in the GCP Console.

  • -appversion is the app version (e.g. the build ID). The GCP Console displays the running version as module - version. For example, main - 1.0.

  • arg1 and arg2 are placeholders for any additional parameters that your application requires.

Using Stackdriver Debugger

After you have set up Stackdriver Debugger for use in your environment and you have started your application, you can open the Debug page in the GCP Console. See Using Stackdriver Debugger for more information.

Send feedback about...

Stackdriver Debugger