Setting Up Stackdriver Debugger for Node.js

Beta

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

Stackdriver Debugger can be enabled for Node.js applications using the Stackdriver Debugger agent for Node.js.

Installing the agent

1. Before installing the agent, make sure you've prepared your environment for Node.js development.

2. The easiest way to install the Stackdriver Debugger agent for Node.js is with npm:

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

   Note: Stackdriver Debugger is compatible with Node.js version 4.0 or greater. Node.js version 5+ is recommended. For more information or to report issues with the Stackdriver Debugger agent, see the agent's source code repository.

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

   Node.js

   View on GitHub Feedback

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

Configuring the agent

You can customize the behavior of the Stackdriver Debugger agent. See the agent configuration for a list of possible configuration options. These options can be passed in the options object passed to the agent's start method.

Running on Google Cloud Platform

The Stackdriver Debugger agent should work without the need to manually provide authentication credentials for instances running on Google Cloud Platform, as long as the Stackdriver Debugger API access scope is enabled on that instance.

App Engine

On Google App Engine, the Stackdriver Debugger API access scope is enabled by default, and the Stackdriver Debugger agent can be used without needing to provide credentials or a project ID.

Container Engine

On Google Container Engine, you need to explicitly add the cloud_debugger OAuth scope when creating the cluster:

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

Compute Engine

For Google Compute Engine instances, you need to explicitly enable the Stackdriver Debugger API access scope for each instance. When creating a new instance through the Google Cloud Platform Console, you can do this in one of two ways under Identity and API access:

• Option 1: Use the Compute Engine default service account and select "Allow full access to all Cloud APIs" under Access scopes.
• Option 2: Select a service account with the Cloud Debugger Agent role, which contains the necessary permissions (or any other role with at least the same permissions). You may need to create one if you don't have one already.

You may add the Stackdriver Debugger API access scope to existing Compute Engine instances if they are running as a non-default service account by adding the Cloud Debugger Agent role to the service account. For more information, see the docs for Creating and Enabling Service Accounts for Instances.

Running elsewhere

If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Debugger, provided that you supply a project ID and credentials to the Stackdriver Debugger agent.

Project ID

You can provide a project ID to the Stackdriver Debugger agent by setting the projectId value in the options object passed to the agent's start method, or you can set the GCLOUD_PROJECT environment variable:

Linux or Mac OS X

export GCLOUD_PROJECT=your-project-id

Windows

set GCLOUD_PROJECT=your-project-id

Powershell:

$env:GCLOUD_PROJECT="your-project-id"

Credentials

Google Cloud Platform client libraries use a strategy called Application Default Credentials (ADC) to find your application's credentials. You can provide credentials to the Stackdriver Debugger agent by setting the keyFilename value in the options object passed to the agent's start method, or you can set the GOOGLE_APPLICATION_CREDENTIALS environment variable. For more information, see Providing credentials to your application.

Example

Node.js

View on GitHub Feedback

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

Source version

Generate a source-context.json file which contains information about the version of the source code used to build the application. This file should be located in the root directory of your application. When you open the Stackdriver Debugger in the Cloud Platform Console, it uses the information in this file to display the correct version of the source.

gcloud beta debug source gen-repo-info-file

Sample application

Node.js

Before running the sample, make sure you've prepared your environment for Node.js development.

View on GitHub Feedback

'use strict';

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

const express = require('express');
const app = express();

app.enable('trust proxy');

app.get('/', (req, res) => {
  // Try using the StackDriver Debugger dashboard to inspect the "req" object
  res.status(200).send('Hello, world!');
});

// Start the server
if (module === require.main) {
  const PORT = process.env.PORT || 8080;
  app.listen(PORT, () => {
    console.log(`App listening on port ${PORT}`);
    console.log('Press Ctrl+C to quit.');
  });
}

Using the debugger

After deployment, you can use Stackdriver Debugger to capture and inspect the call stack and local variables in your application.