Node.js agent for Google Cloud Debug

This module is experimental, and should be used by early adopters. This module uses APIs there may be undocumented and may be subject to change without notice.

This module provides Cloud Debug support for Node.js applications. Google Cloud Debug is a feature of Google Cloud Platform that lets you debug your applications in production without stopping or pausing your application. Here's an introductory video:

Prerequisites

• Your application will need to be using Node.js version 0.12 or greater. Node.js v5+ is recommended. (Node.js v5.2.0 is not supported on account of this bug)
• The source of your application is uploaded to a cloud source repository. The Debugger UI needs the source to be available in order to set breakpoints.

Quick Start (Node.js v4.x+)

# Install with `npm` or add to your `package.json`.
npm install --save @google/cloud-debug

# Change the start command of your application in package.json
   ...
   "scripts" {
     "start": "node --require @google/cloud-debug server.js"
   ...

Deploy your application, and navigate to the Debug tab within the Google Developers Console to set breakpoints and start debugging.

Installation

1. Install the debug agent module via npm or add it to your package.json.

   npm install --save @google/cloud-debug

2. Ensure that the module gets loaded during your application's startup. The best way to do this is via the --require command line option available in Node.js v4. You should add this option to the startup script section in your package.json.

   "scripts": {
      "start": "node --require @google/cloud-debug server.js",
   

   If you are using Node.js v0.12.x, you will not be able to use the --require command line option. Instead you will have to manually load the debug agent module in the startup script of your application. For example, you may want to add the following to your server.js:

   require('@google/cloud-debug');

Running on Google Cloud Platform

There are three different services that can host Node.js application to Google Cloud Platform.

Google App Engine Managed VMs

If you are using Google App Engine Managed VMs, you do not have to do any additional configuration.

Google Compute Engine

Your VM instances need to be created with cloud-platform scope if created via gcloud or the 'Allow API access' checkbox selected if created via the console (see screenshot).

If you already have VMs that were created without API access and do not wish to recreate it, you can follow the instructions for using a service account under running elsewhere.

Google Container Engine

Container Engine nodes need to also be created with the cloud-platform scope, which is configurable during cluster creation. Alternatively, you can follow the instructions for using a service account under running elsewhere. It's recommended that you store the service account credentials as Kubernetes Secret.

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 Cloud Debug.

1. You will need to specify the numeric project ID of your project. Your numeric project ID, or project number, is visible the Project information section on your project's dashboard.

    export GCLOUD_PROJECT_NUM=<your numeric project id>
   

2. You need to provide service account credentials to your application. The recommended way is via Application Default Credentials.

3. Create a new JSON service account key.

4. Copy the key somewhere your application can access it. Be sure not to expose the key publicly.

5. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the full path to the key. The debug agent will automatically look for this environment variable.

6. Alternatively, if you are running your application on a machine where your are using the gcloud command line tools, and are logged using gcloud auth login, you already have sufficient credentials, and a service account key is not required.

At this point you can deploy your application to and the debug agent will activate with no further action. If you want to run your application locally, you can still use the cloud debug agent, with a few additional steps:

Using the Debugger

Once your application is running (deployed, or elsewhere), you should be able to use the Debug UI in your Cloud developer console. You can find the Debug UI in the 'Operations > Debug' section in the navigation panel, or by simply searching for 'Debug' in the developer console.

You can browse the code, and set a snapshot by clicking in the gutter (line number area). Once you set a snapshot, the debug agent will insert a momentary breakpoint at the code location in the running instances of the application.

As soon as that line of code is reached in any of the running instances of your application, the stack traces, local variables, and watch expressions are captured, and your application continues.

Limitations and Requirements

• The root directory of your application needs to contain a package.json file.
• You can set breakpoint conditions and watch expressions to be evaluated in the context of your application. This leads to some issues you should be aware of
  • You may be able to view sensitive data of your own users by looking at the values of the variables.
  • The debug agent tries to ensure that all conditions and watchpoints you add are read-only and have no side effects. It catches, and disallows, all expressions that may have static side effects to prevent accidental state change. However, it presently does not catch expressions that have dynamic side-effects. For example, o.f looks like a property access, but dynamically, it may end up calling a getter function. We presently do NOT detect such dynamic-side effects.
• With Node.js 4.x and older, your application may experience a performance impact when there are breakpoint active. There should be no impact to performance when no breakpoints are active. Node.js v5.x does not have this issue.
• Node.js v0.10.x or older are not supported as they lack some necessary APIs to avoid a permanent (life of the application) performance hit.