Profiling Go applications

This page describes how to modify your Go application to capture profiling data and have that data sent to your Google Cloud project. For general information about profiling, see Profiling concepts.

Profile types for Go:

• CPU time
• Heap
• Allocated heap
• Contention (Go mutex)
• Threads (Go goroutine)

Supported Go language versions:

• All officially maintained Go releases, unless otherwise noted. For more information, see Go language release policy.

Supported profiling agent versions:

• The most recent release of the agent is supported. In general, releases older than one year aren't supported. We recommend that you use the most recently released version of the agent.

Supported operating systems:

• Linux. Profiling Go applications is supported for Linux kernels whose standard C library is implemented with glibc or with musl. For configuration information specific to Linux Alpine kernels, see Running on Linux Alpine.

Supported environments:

• Compute Engine
• Google Kubernetes Engine (GKE)
• App Engine flexible environment
• App Engine standard environment (requires Go 1.11 or higher)
• Outside of Google Cloud (For information on the additional configuration requirements, see Profiling applications running outside of Google Cloud.)

Enabling the Profiler API

Before you use the profiling agent, ensure that the underlying Profiler API is enabled. You can check the status of the API and enable it if necessary by using either the Google Cloud CLI or the Google Cloud console:

Grant IAM role to service account

If you are deploying your application on Google Cloud resources and if you are using the default service account and haven't modified the role grants to that service account, then you can skip this section.

If you do any of the following, then you need to grant the service account the IAM role of Cloud Profiler Agent (roles/cloudprofiler.agent):

1. You are using the default service account but modified its role grants.
2. You are using a user-created service account.
3. You are using workload identity, grant the Cloud Profiler Agent role to the Kubernetes service account.

You can grant an IAM role to a service account by using the Google Cloud console or the Google Cloud CLI. For example, you could use the gcloud projects add-iam-policy-binding command:

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
    --member serviceAccount:MY_SVC_ACCT_ID@GCP_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudprofiler.agent

Before you use the previous command, replace the following:

• GCP_PROJECT_ID: Your project ID.
• MY_SVC_ACCT_ID: The name of your service account.

For detailed information, see Manage access to projects, folders, and organization.

Using Cloud Profiler

In all of the supported environments, you use the Profiler by importing the package in your application and then initializing the Profiler as early as possible in your application.

You can enable Mutex-contention profiling (“Contention” in the interface) by setting the MutexProfiling configuration option to true.

For more information on the Profiler API, including all the configuration options, see the public API docs.

// snippets is an example of starting cloud.google.com/go/profiler.
package main

import (
	"cloud.google.com/go/profiler"
)

func main() {
	cfg := profiler.Config{
		Service:        "myservice",
		ServiceVersion: