Profiling applications running outside Google Cloud Platform

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

In this scenario, your application 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, on the project selector page, click Create to begin creating a new GCP project.

Go to the Project selector page

Enable the Profiler API

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

  1. Go to the APIs & Services dashboard:

    Go to APIs & services

  2. Click the Add APIs and Services button.

    Add APIs and Services

  3. Search for Profiler API.

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

  5. 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 applications:

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


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


When your application isn't able to access the Compute Engine metadata server, messages similar to the following are displayed:

     Error making HTTP request for
To stop these messages, add -cprof_zone_name=[VALUE] to your agent configuration flags and restart your application. For this scenario, replace [VALUE] with a descriptive string such as "test".


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

projectId: '[GCP_PROJECT_ID]',
serviceContext: {


Specify an additional parameter, project_id, in the start method call described in Profiling Python applications:

googlecloudprofiler.start(..., project_id='[GCP_PROJECT_ID]')

What's next

To learn about the Profiler graph and controls, go to Using the Stackdriver Profiler Interface. For advanced information, go to the following:

Kunde den här sidan hjälpa dig? Berätta:

Skicka feedback om ...

Stackdriver Profiler
Behöver du hjälp? Besök vår supportsida.