This page describes how to configure your environment and your
Go application to use Stackdriver Debugger.
For some environments, you must explicitly specify the access scope to let the
Stackdriver Debugger agent send data.
We recommend setting the
broadest possible access scope and then using Cloud Identity and Access Management
to restrict access.
In keeping with this best practice, set the access scope to be all Cloud APIs
with the option
App Engine standard environment
The Stackdriver Debugger agent for Go is not supported in App Engine standard environment yet.
App Engine flexible environment
The Stackdriver Debugger agent for Go is not supported in App Engine flexible environment yet.
Make sure your cluster is created with one of the following access scopes:
gcloud container clusters create EXAMPLE-CLUSTER-NAME \ --scopes https://www.googleapis.com/auth/cloud-platform
Follow the instructions for Compute Engine.
Make sure your Compute Engine VM instances are running a 64-bit Debian Linux image.
Make sure your Compute Engine VM instances are created with the access scope option Allow full access to all Cloud APIs, or have one of the following access scopes:
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.
To get the correct debugging information, build your application without the default optimizations. The following sample commands demonstrate how to disable optimizations when using go1.10 or a later version:
go build -gcflags=all='-N -l'
-Nto disable optimizations and
-lto disable inlining.
Download the debugger 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 and install the debug agent:
go get -u cloud.google.com/go/cmd/go-cloud-debug-agent
Start the agent and your program:
go-cloud-debug-agent -sourcecontext=[PATH_TO_FILE] -appmodule=[APP_NAME] \ -appversion=[APP_VERSION] -- [PATH_TO_BINARY] [ARG1] [ARG2]
PATH_TO_FILEspecifies the relative path to the JSON-formatted file containing your source context configuration. See Selecting Source Code Automatically for information on generating this file.
APP_NAMEis the name of your application or service. This, along with the version, is used to identify your application in the GCP Console.
APP_VERSIONis an application-supplied version marker. For example, you could use a build number. The GCP Console displays the running version as
module - version. For example,
main - 1.0.
PATH_TO_BINARYspecifies the relative path to your application binary.
ARG2are placeholders for any additional arguments that your application requires.
go-cloud-debug-agent -appmodule=main -appversion=1.0 -- bin/my-app my-arg
The debugger is now ready for use with your app.
To have the Debug page in the GCP Console automatically display source code matching the deployed app, see Selecting Source Code Automatically.
Local and Elsewhere
The Stackdriver Debugger agent for Go is supported only in the Kubernetes Engine and Compute Engine environments. It is not supported for local or other environments.