@google-cloud/debug-agent

Stackdriver Debugger agent for Node.js

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

This module provides Stackdriver Debugger support for Node.js applications. Stackdriver Debugger 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

• Stackdriver Debugger is comptible with Node.js version 0.12 or greater. Node.js v5+ is recommended.

Quick Start

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

// Require and start in the startup of your application:
require('@google-cloud/debug-agent').start({ allowExpressions: true });
// No auth necessary if your code is running on Google Cloud Platform.

// ... or, if you are running elsewhere, you can manually provide credentials:
require('@google-cloud/debug-agent').start({
  allowExpressions: true,
  projectId: 'particular-future-12345',
  keyFilename: '/path/to/keyfile.json'
});

This starts the automatic Debugger Agent that enables your app to be debuggable using the Stackdriver Stackdriver Debug view within the Google Cloud Console. You can start adding snapshots and log-points to your application.

Running on Google Cloud Platform

The Stackdriver Debugger Agent should work without manually provided authentication credentials for instances running on Google Cloud Platform, as long as the Stackdriver Debugger API access scope is enabled on that instance. For Google App Engine instances, this is automatic if the Debugger API has been enabled for your project (which is the default).

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

• Use the Compute Engine default service account and select "Allow full access to all Cloud APIs" under Access scopes.
• 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 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.

1. You will need to specify your project name. Your project name is visible in the Google Cloud Console, it may be something like particular-future-12345. If your application is running on Google Cloud Platform, you don't need to specify the project name. You can specify this either in the module options, or through an environment variable:

     // In your app:
     var debug = require('@google-cloud/debug-agent').start({
       allowExpressions: true,
       projectId: 'particular-future-12345',
       keyFilename: '/path/to/keyfile.json'
     });
   

     # Or in Bash:
     export GCLOUD_PROJECT='particular-future-12345'
   

2. You need to provide service account credentials to your application.

• The recommended way is via Application Default Credentials.

  1. Create a new JSON service account key.
  2. Copy the key somewhere your application can access it. Be sure not to expose the key publicly.
  3. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the full path to the key. The debug agent will automatically look for this environment variable.

• 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.

• Alternatively, you may set the keyFilename or credentials configuration field to the full path or contents to the key file, respectively. Setting either of these fields will override either setting GOOGLE_APPLICATION_CREDENTIALS or logging in using gcloud. For example:

  // Require and start the agent with configuration options
  require('@google-cloud/debug-agent').start({
    // Allow the evaluation of watch expressions and snapshot conditions:
    allowExpressions: true,
  
    // The path to your key file:
    keyFilename: '/path/to/keyfile.json',
  
    // Or the contents of the key file:
    credentials: require('./path/to/keyfile.json')
  });
  

See the configuration object for more details.

1. 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
   

Debugger Agent Settings

You can customize the behaviour of the automatic 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 start function.

  require('@google-cloud/debug-agent').start({
    // .. auth settings ..

    // debug agent settings:
    allowExpressions: true,
    serviceContext: {
        service: 'my-service',
        version: 'version-1'
    },
    capture: { maxFrames: 20, maxProperties: 100 }
  });

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 'STACKDRIVER -> Debug' section in the navigation panel, or by simply searching for 'Debug' in the cloud console.

If your source is hosted in a cloud source repository, Stackdriver Debugger will display the source code of your application automatically. Alternatively, you can also point the debugger to local files, a GitHub or Bitbucket repository, through a Source Capture, or you can simply type in a filename and line number. More details are on source options are available here.

If you have the source available, you can 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 snapshot 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 snapshots active. There should be no impact to performance when no snapshots 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.

Changelog

2017-03-14, Version 1.0.0 (Experimental), @dominicdkramer

Semver-major changes

• Evaluation of expressions is no longer allowed by default. It can be enabled using the allowExpressions configuration option.

Commits

• [3256eed494] - Update options in README (#249) (Matthew Loring) #249
• [36a0c2c012] - Add allowExpressions option (#244) (Matthew Loring) #244
• [48a9952ec0] - Report FUNCTION_NAME as the description (#247) (Ali Ijaz Sheikh)
• [cfc4f3fedf] - Relax configuration rules for agent (#245) (Matthew Loring) #245
• [8358f670e2] - Remove unused dependencies (#246) (Matthew Loring) #246
• [6615823884] - Reduce test loudness (#243) (Ali Ijaz Sheikh)
• [52b5bd3f52] - deal with source-context read errors (#242) (Ali Ijaz Sheikh)
• [ce7ce0bbe9] - improve normalizeConfig test (#241) (Ali Ijaz Sheikh)
• [21a8f5accf] - merge configs using a deep copy (#240) (Ali Ijaz Sheikh)
• [75974f56d5] - Document minorVersion_ as an internal property (#239) (Ali Ijaz Sheikh)