Setting Up Stackdriver Debugger for Node.js

The Stackdriver Debugger agent for Node.js can be used to inspect the state of Node.js applications running on Google Cloud Platform, on other cloud providers, in your data centers, or on your local workstation.

Before you begin

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Cloud Platform project.

    Go to the Manage resources page

  3. Enable the Stackdriver Debugger API.

    Enable the API

  4. Prepare your environment for Node.js development.

    Go to the Node.js setup guide

Installing the agent

Stackdriver Debugger agent for Node.js lets you inspect the state of a Node.js application, at any code location, without stopping or slowing down the running app.

  1. Use npm to install the package:

    npm install --save @google-cloud/debug-agent
  2. 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):


    If not running on Google Cloud Platform, specify credentials (see Running locally and elsewhere):

      projectId: 'your-project-id',
      keyFilename: '/path/to/key.json'

For more information on installation, see the documentation for the Stackdriver Debugger agent for Node.js. You can also report issues using the issue tracker.

Configuring the agent

You can customize the behavior of the Stackdriver Debugger agent for Node.js. See the agent configuration on GitHub 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

Using the Stackdriver Debugger agent for Node.js requires the Cloud IAM Debugger Agent role. Most Google Cloud Platform compute platforms provide this role by default.

App Engine

Google App Engine grants the Debugger Agent role by default.

The Stackdriver Debugger agent for Node.js can be used without needing to explicity provide credentials.

Stackdriver Debugger is automatically enabled for App Engine environment applications. No additional setup is required.

Kubernetes Engine

On Google Kubernetes Engine, you must add the cloud_debugger access scope when creating the cluster:

gcloud container clusters create example-cluster-name --scopes

Compute Engine

When using Google Compute Engine VM instances, add the cloud-platform access scope to each instance. When creating a new instance through the Google Cloud Platform Console, you can do this in the Identity and API access section of the Create Instance panel. Use the Compute Engine default service account or another service account of your choice, and select Allow full access to all Cloud APIs in the Identity and API access section. Whichever service account you select, ensure that it has been granted the Debugger Agent role in the IAM & admin section of the Cloud Platform Console.

Running locally and elsewhere

To use the Stackdriver Debugger agent for Node.js outside of Google Cloud Platform, you must supply your GCP project ID and appropriate service account credentials directly to the Stackdriver Debugger agent for Node.js. This applies to running the agent on your own workstation, on your data center's computers, or on the VM instances of another cloud provider. For more information see Obtaining and providing service account credentials manually.


  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

For more information see Selecting Source Code Manually.

Sample application

'use strict';


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.');


After deployment, you can begin debugging in the Cloud Platform Console Debugger dashboard:

Go to the Debugger dashboard

For more information, see Using Debug Snapshots and Using Debug Logpoints.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Debugger