Setting Up Cloud Debugger for Go

Overview

This page describes how to configure your environment and your Go application to use Cloud Debugger. For some environments, you must explicitly specify the access scope to let the Cloud Debugger agent send data. We recommend setting the broadest possible access scope and then using 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 cloud-platform.

Language versions and compute environments

Cloud Debugger is available for Go 1.9 and higher on the following compute environments:

App Engine Standard environment App Engine Flexible environment Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos on Google Cloud VMs and Containers running elsewhere Cloud Functions

Setting up Cloud Debugger

To set up Cloud Debugger, complete the following tasks:

  1. Verify the Cloud Debugger API is enabled for your project.

  2. Install and configure the Debugger on the compute environment you're using.

  3. Select your source code.

Verifying the Cloud Debugger API is enabled

To begin using Cloud Debugger, ensure that the Cloud Debugger API is enabled. Cloud Debugger is enabled by default for most projects.
Enable Cloud Debugger API

Google Kubernetes Engine

GCLOUD

To enable Debugger using gcloud, complete the following steps:

  1. Create your cluster with one of the following access scopes:

    • https://www.googleapis.com/auth/cloud-platform grants your cluster access to all Google Cloud APIs.

    • https://www.googleapis.com/auth/cloud_debugger grants your cluster access to only the Debugger API. Use this access scope to harden your cluster's security.

    gcloud container clusters create example-cluster-name \
           --scopes=https://www.googleapis.com/auth/cloud_debugger
    
  2. Add the following lines to your Dockerfile to add the Debugger agent to your containerized app:

    RUN go get -u cloud.google.com/go/cmd/go-cloud-debug-agent \
        go-cloud-debug-agent -sourcecontext=[PATH_TO_FILE] -appmodule=[APP_NAME] \
        -appversion=[APP_VERSION] -- [PATH_TO_BINARY] [ARG1] [ARG2]
    

    Where:

    • PATH_TO_FILE specifies the relative path to the JSON-formatted file containing your source context configuration.

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

    • APP_VERSION is an application-supplied version marker. For example, you could use a build number. The Cloud Console displays the running version as module - version. For example, main - 1.0.

    • PATH_TO_BINARY specifies the relative path to your application binary.

    • ARG1 and ARG2 are placeholders for any additional arguments that your application requires.

The debugger is now ready for use when you deploy your containerized app.

For more detailed information on creating a cluster, see Creating a cluster.

CONSOLE

To enable Debugger using the console, complete the following steps:

  1. After selecting your cluster type, click More options from the Node pools pane:

    Node pool field showing red rectangle over the more options button.

  2. Select one of the following from the Security pane:

    • Allow full access to all Cloud APIs.

    • Allow access for each API and then select Enabled for Cloud Debugger.

Compute Engine

  1. Make sure your Compute Engine VM instances are running a 64-bit Debian Linux image.

  2. 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:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  3. The current Go compiler's optimizations interfere with accurate debugging. As a result, Cloud 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'
    

    The preceding gcflags value includes -N to disable optimizations and -l to disable inlining.

  4. Download the debugger agent.

    The Cloud 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 Cloud 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
    
  5. 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]
    

    Where:

    • PATH_TO_FILE specifies the relative path to the JSON-formatted file containing your source context configuration.

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

    • APP_VERSION is an application-supplied version marker. For example, you could use a build number. The Cloud Console displays the running version as module - version. For example, main - 1.0.

    • PATH_TO_BINARY specifies the relative path to your application binary.

    • ARG1 and ARG2 are placeholders for any additional arguments that your application requires.

    For example:

    go-cloud-debug-agent -appmodule=main -appversion=1.0 -- bin/my-app my-arg
    

The debugger is now ready for use with your app.

Local and elsewhere

The Cloud Debugger agent for Go is supported for local or other environments that use Go 1.9 and earlier.