Profiling applications running outside Google Cloud

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

In this scenario, your application and the Cloud Profiler agent run outside Google Cloud, but you use the Cloud Profiler interface to analyze the profiling data.

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

  1. Create a Google Cloud 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 Google Cloud project.

Create a Google Cloud project

In the Cloud Console, on the project selector page, click Create to begin creating a new Cloud project.

Go to the project selector page

Enable the Profiler API

In the Cloud 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 Cloud 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].iam.gserviceaccount.com \
         --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].iam.gserviceaccount.com
    

    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 Google Cloud project

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

Go

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

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

Java

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

 -cprof_project_id=[GCP_PROJECT_ID]

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 169.254.169.254:80/computeMetadata/v1/instance/zone
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".

Node.js

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

projectId: '[GCP_PROJECT_ID]',
serviceContext: {
  ...
}

Python

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 Cloud Profiler Interface. For advanced information, go to the following: