Setting Up Cloud Debugger for Node.js

This page describes how to configure your environment and your Node.js application to use Cloud Debugger. For some environments, you must explicitly specify the access scope to let the Cloud Debugger agent send data. We recommend setting the broadest possible access scope and then using Cloud Identity and Access Management to restrict access. In keeping with this best practice, set the access scope to be all Cloud APIs with the option cloud-platform.

Before you begin

To begin using Cloud Debugger, ensure that the Cloud Debugger API is enabled.
Enable Cloud Debugger API

App Engine

  1. Use npm to install the package:

    npm install --save @google-cloud/debug-agent

  2. Enable agent at the top of your app's main script or entry point (but after @google/cloud-trace if you are also using it):

    require('@google-cloud/debug-agent').start();

The debugger is now ready for use with your app.

To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.

Google Kubernetes Engine

GCLOUD

To enable Debugger using gcloud, complete the following steps:

  1. Create your cluster with one of the following access scopes:

    • https://www.googleapis.com/auth/cloud-platform grants your cluster access to all Google Cloud APIs.

    • https://www.googleapis.com/auth/cloud_debugger grants your cluster access to only the Debugger API. Use this access scope to harden your cluster's security.

    gcloud container clusters create example-cluster-name \
       --scopes=https://www.googleapis.com/auth/cloud_debugger

  2. Add the following line to your Dockerfile to add the Debugger agent:

    RUN  npm install --save @google-cloud/debug-agent

  3. Enable the agent at the top of your app's main script or entry point (but after @google/cloud-trace if you are also using it):

    require('@google-cloud/debug-agent').start({
  serviceContext: {
    service: 'SERVICE',
    version: 'VERSION'
  }
});

    Where:

    • SERVICE is a name for your app, such as MyApp, Backend, or Frontend.
    • VERSION is a version, such as v1.0, build_147, or v20170714.

    We recommend setting these from environment variables so you do not need to change the source code with each deployment.

The debugger is now ready for use when you deploy your containerized app.

To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.

CONSOLE

To enable Debugger using the console, complete the following steps:

  1. After selecting your cluster type, click More options from the Node pools pane:

    Node pools options

  2. Select one of the following from the Security pane:

    • Allow full access to all Cloud APIs.

    • Allow access for each API and then select Enabled for Cloud Debugger.

Compute Engine

  1. Make sure your Compute Engine instances are created with the access scope option Allow full access to all Cloud APIs, or have one of the following access scopes:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger

  2. Use npm to install the package:

    npm install --save @google-cloud/debug-agent

  3. Enable the agent at the top of your app's main script or entry point (but after @google/cloud-trace if you are also using it):

    require('@google-cloud/debug-agent').start({
  serviceContext: {
    service: 'SERVICE',
    version: 'VERSION'
  }
});

    Where:

    • SERVICE is a name for your app, such as MyApp, Backend, or Frontend.
    • VERSION is a version, such as v1.0, build_147, or v20170714.

    We recommend setting these from environment variables so you do not need to change the source code with each deployment.

The debugger is now ready for use with your app.

To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting Source Code Automatically.

Cloud Run and Cloud Run for Anthos on Google Cloud

  1. Use npm to install the package:

    npm install --save @google-cloud/debug-agent

  2. Enable the agent at the top of your app's main script or entry point (but after @google/cloud-trace if you are also using it):

    require('@google-cloud/debug-agent').start();

    The debugger is now ready for use when you deploy your app.

Local and elsewhere

  1. Use npm to install the package:

    npm install --save @google-cloud/debug-agent

  2. Download service account credentials.

    To use the Cloud Debugger agent for Node.js on machines not hosted by Google Cloud, the agent must use a Google Cloud service account credentials to authenticate with the Cloud Debugger Service.

    Use the Cloud Console Service Accounts page to create a credentials file for an existing or new service account. The service account must have at least the Cloud Debugger Agent role.

  3. Configure and enable the agent with the downloaded credentials:

    require('@google-cloud/debug-agent').start({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
  serviceContext: {
    service: 'SERVICE',
    version: 'VERSION'
  }
});

    Where:

    • SERVICE is a name for your app, such as MyApp, Backend, or Frontend.
    • VERSION is a version, such as v1.0, build_147, or v20170714.

    We recommend setting these from environment variables so you do not need to change the source code with each deployment.

The debugger is now ready for use with your app.

The Debug page in the Cloud Console can display local source files, without upload, for local development. See Selecting Source Code Manually.