Profiling Go code

This page describes setting up Stackdriver Profiler for profiling Go code. For Go, Profiler offers CPU, heap, contention, and threads profiling. Contention profiling captures information about Go mutexes. Thread profiling captures information about Goroutines, not operating-system threads. For more information on profiling and the types of profiling available, see Profiling concepts.

You can use the profiling agent on Linux in the following environments:

The profiler agent for each environment supports all officially maintained Go releases, unless otherwise noted. See the Go language release policy for more information.

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 Cloud SDK gcloud command-line tool or the Cloud Console:

Cloud SDK

  1. If you have not already installed the Cloud SDK on your workstation, see Google Cloud SDK.

  2. Run the following command:

    gcloud services enable cloudprofiler.googleapis.com
    

For more information, see gcloud services.

Cloud Console

  1. Go to the APIs & Services dashboard:

    Go to APIs & services

  2. Select the project you will use to access the API.

  3. Click the Add APIs and Services button.

    Add APIs and Services

  4. Search for Profiler API.

  5. In the search results, select Stackdriver Profiler API.

  6. If API enabled is displayed, then the API is already enabled. If not, click the Enable button.

Using Stackdriver 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 code.

By default, the profiling agent for Go has the following profile types enabled:

  • CPU
  • Heap
  • Heap Alloc
  • Threads

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.

Compute Engine and Google Kubernetes Engine

For Compute Engine and GKE, the code additions look like this:

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

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

func main() {
	// Profiler initialization, best done as early as possible.
	if err := profiler.Start(profiler.Config{
		Service:        "myservice",
		ServiceVersion: "1.0.0",
		// ProjectID must be set if not running on GCP.
		// ProjectID: "my-project",
	}); err != nil {
		// TODO: Handle error.
	}
}

In both the Compute Engine and GKE environments, the profiler.Config includes two parameters:

  • Service: A name for the service being profiled
  • ServiceVersion: (optional) The version of the service being profiled

See Service name and version arguments for more information on these configuration options.

App Engine environments

For the App Engine flexible environment and the App Engine standard environment, the code additions are nearly identical to those for Compute Engine and GKE. There is one exception. In both App Engine environments, the Service and ServiceVersion parameters are derived from the environment, so you don't have to specify them.

// appengine is an example of starting cloud.google.com/go/profiler on
// App Engine.
package main

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

func main() {
	// Profiler initialization, best done as early as possible.
	if err := profiler.Start(profiler.Config{
		// Service and ServiceVersion can be automatically inferred when running
		// on App Engine.
		// ProjectID must be set if not running on GCP.
		// ProjectID: "my-project",
	}); err != nil {
		// TODO: Handle error.
	}
}

However, if you run the application locally, set the ProjectID (the ID of your GCP project) and Service parameters in profiler.Config, since they cannot be derived from a local environment. You don't need to set ServiceVersion.

If you are using App Engine standard environment, see Migrating your app to Go 1.11 for detailed information on changes you might need to make to your application. Also, you must use Cloud SDK version 226.0.0 or later. To update the Cloud SDK, run the following command:

    gcloud components update

To run your application:

  1. Update the dependencies:

    go get -u cloud.google.com/go/profiler
    
  2. Deploy the application to your App Engine flexible environment or to your App Engine standard environment:

    go app deploy [DEPLOYMENT]
    

    where DEPLOYMENT is the path to your configuration file. For example, DEPLOYMENT might be main/app.yaml.

Analyzing data

After Profiler has collected data, you can view and analyze this data using the Profiler interface. To get started using this interface, see Opening the Profiler interface.

Service name and version arguments

When you load the Profiler agent, you specify a service-name argument and an optional service-version argument to configure it.

The service name lets Profiler collect profiling data for all replicas of that service. The profiler service ensures a collection rate of one profile per minute, on average, for each service name across each combination service versions and zones.

For example, if you have a service with two versions running across replicas in three zones, the profiler will create an average of 6 profiles per minute for that service.

If you use different service names for your replicas, then your service will be profiled more often than necessary, with a correspondingly higher overhead.

When selecting a service name:

  • Choose a name that clearly represents the service in your application architecture. The choice of service name is less important if you only run a single service or application. It is more important if your application runs as a set of micro-services, for example.

  • Make sure to not use any process-specific values, like a process ID, in the service-name string.

  • The service-name string must match this regular expression:

    ^[a-z]([-a-z0-9_.]{0,253}[a-z0-9])?$

A good guideline is to use a static string like imageproc-service as the service name.

The service version is optional. If you specify the service version, Profiler can aggregate profiling information from multiple instances and display it correctly. It can be used to mark different versions of your services as they get deployed. The Profiler UI lets you filter the data by service version; this way, you can compare the performance of older and newer versions of the code.

The value of the service-version argument is a free-form string, but values for this argument typically look like version numbers, for example, 1.0.0 or 2.1.2.

Agent logging

The profiling agent can report debug information in its logs. To enable, set the DebugLogging option to true when starting the agent.

profiler.Start(profiler.Config{..., DebugLogging: true});

Running with Linux Alpine

If you use Docker images that run with Linux Alpine (such as golang:alpine or just alpine), you might see the following authentication error:

connection error: desc = "transport: authentication handshake failed: x509: failed to load system roots and no roots provided"

Note that to see the error you must have agent logging. By default the agent doesn't output any log messages.

The error indicates that the Docker images with Linux Alpine don't have the root SSL certificates installed by default. Those certificates are necessary for the profiling agent to communicate with the profiler API. To resolve this error, add the following apk commands to your Dockerfile:

FROM alpine
...
RUN apk update \
 && apk add --no-cache ca-certificates

You then need to rebuild and redeploy your application.

What's next

See Using the Stackdriver Profiler Interface for detailed information on different features of Profiler:

  • Learn about the Profiler controls.
  • Learn how to zoom in on specific frames.
  • Learn how to filter and focus the graph.
  • Learn how to compare profiles.
Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Profiler