Setting Up Stackdriver Debugger for Node.js

Beta

This is a beta release of the Stackdriver Debugger agent for Node.js. This library might be changed in backward-incompatible ways and is not subject to any SLA or deprecation policy.

Note: Stackdriver Debugger is compatible with Node.js version 4 or greater. Node.js v5+ is recommended.

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 GCP Console automatically display source code matching the deployed app, see Selecting Source Code Automatically.

Kubernetes Engine

1. Make sure your cluster is created with one of the following access scopes:

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

   Example:

   gcloud container clusters create EXAMPLE-CLUSTER-NAME \
       --scopes https://www.googleapis.com/auth/cloud-platform
   

2. Follow the instructions for Compute Engine.

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 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 GCP Console automatically display source code matching the deployed app, see Selecting Source Code Automatically.

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 Stackdriver Debugger agent for Node.js on machines not hosted by Google Cloud Platform, the agent must use a GCP service account credentials to authenticate with the Stackdriver Debugger Service.

   Use the GCP Console Service Accounts page to create a credentials file for an existing or new service account. The service account must have at least the Stackdriver 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 GCP Console can display local source files, without upload, for local development. See Selecting Source Code Manually.

Note: You can find the debugger agent's code and documentation on GitHub.