Profiling Outside Google Cloud Platform

This page describes how to profile code running outside Google Cloud Platform.

In this scenario, your code and the Stackdriver Profiler agent run outside GCP, but you use the Stackdriver Profiler interface to analyze the profiling data.

Using the Profiler interface to analyze profiling data requires a GCP project. The profiling agent running elsewhere must be able to send the profiles back for analysis. To enable this, you must:

  1. Create a GCP project and enable the API.
  2. Obtain credentials for the profiling agent to use when uploading profiles.
  3. Configure the agent to use the credentials and the ID of the GCP project.

Create a Google Cloud Platform project

In the GCP Console, go to the Manage resources page and create a new project.

Go to the Manage resources page

Enable the Profiler API

In the GCP Console page for your new project, go to the APIs & Services page:

Go to APIs & services

  1. Click the Enable APIs and Service button.
  2. Search for “Stackdriver”.
  3. In the search results, click through to “Profiler API”.
  4. If “API enabled” is displayed, then the API is already enabled. If not, click the Enable button.

Obtain credentials for the agent

There are two ways to obtain credentials for the agent to use:

  • Let the agent use a service account with private-key authentication
  • Let the agent use application default credentials (ADC).

Using service accounts

To enable the agent to use a service account with private-key authentication, you must:

  1. Create a service account. For example, using the Cloud SDK:

    gcloud iam service-accounts create [MY-SVC-ACCT-ID] --display-name "my service account"

    See Creating a service account for more information.

  2. Grant the service account the roles/cloudprofiler.agent role, so that it can write profiling data. For example, using the Cloud SDK:

     gcloud projects add-iam-policy-binding [GCP-PROJECT-ID] \
         --member serviceAccount:[MY-SVC-ACCT-ID]@[GCP-PROJECT-ID] \
         --role roles/cloudprofiler.agent

    See Granting roles to service accounts for more information.

  3. Create a JSON key for the service account. For example, using the Cloud SDK:

     gcloud iam service-accounts keys create \
         ~/key.json \
         --iam-account [MY-SVC-ACCT-ID]@[GCP-PROJECT-ID]

    See Creating service account keys for more information.

  4. On the machine where the profiling agent will run:

    1. Put a copy of the file containing the JSON key you just created.
    2. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the fully qualified name of the file containing the JSON key. This environment variable must be visible to the process running the profiling agent, so if you use a script or Dockerfile to run the process, include the environment variable there.

Using application default credentials

To enable the agent to use application default credentials, you obtain user-access credentials via a web flow and put them where the Application Default Credentials library expects them. These credentials act as a proxy for a service account.

To use application default credentials, run the following Cloud SDK command:

 gcloud auth application-default login

and follow the steps this command guides you through.

Linking the agent to a GCP project

The profiling agent must be configured to specify the ID of your GCP project so it can upload profiles. The mechanism for doing this depends on the language.


Specify an additional parameter, ProjectID, in the profiler.Config object described in Profiling Go Code:

 profiler.Config{ProjectID: "[GCP_PROJECT_ID]", ...}


Specify an additional Java agent configuration flag, cprof_project_id, on the Java invocation:



Specify an additional parameter, projectID, in the serviceContext object described in Profiling Node.js Code:

projectId: '[GCP_PROJECT_ID]',
serviceContext: {
Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Profiler