Overview
This page describes how to configure your environment and your
Node.js application to use Cloud Debugger.
For some environments, you must explicitly specify the access scope to let the
Cloud Debugger agent send data.
We recommend setting the
broadest possible access scope and then using Identity and Access Management
to restrict access.
In keeping with this best practice, set the access scope to be all Cloud APIs
with the option cloud-platform
.
Language versions and compute environments
Cloud Debugger is available for Node.js 9 and higher on the following compute environments:
App Engine Standard environment | App Engine Flexible environment | Compute Engine | Google Kubernetes Engine | Cloud Run | Cloud Run for Anthos | VMs and Containers running elsewhere | Cloud Functions |
---|---|---|---|---|---|---|---|
Setting up Cloud Debugger
To set up Cloud Debugger, complete the following tasks:
Verify the Cloud Debugger API is enabled for your project.
Install and configure the Debugger on the compute environment you're using.
Select your source code.
Verifying the Cloud Debugger API is enabled
To begin using Cloud Debugger, ensure that the Cloud Debugger API is enabled. Cloud Debugger is enabled by default for most projects.Enable Cloud Debugger API
Canary snapshots and logpoints
To prevent snapshots and logpoints from being loaded on all running instances at the same time, and possibly causing the job to be taken down because of a potential bug in the Debugger agent, enable canary mode for the Debugger agent. When canary mode is enabled, a snapshot or logpoint is applied to a subset of running instances and Debugger verifies that the snapshot or logpoint doesn't adversely affect those instances. After the verification is complete, the snapshot or logpoint is applied to all instances.
To learn how to use Debugger in canary mode, go to the the Debug snapshots and Debug logpoints pages.
Enabling canary snapshots and logpoints
When you install the latest version of the Debugger agent, you have the option to enable or disable canarying. Canarying is disabled by default.
When to enable canary snapshots and logpoints
To protect deployment and production-critical workloads, enable canarying when debugging these workloads.
If you have a single instance, you can still debug with canarying enabled, but your single instance runs without canarying the snapshot or logpoint.
When not to enable canary snapshots and logpoints
Don't enable canarying on workloads that have an execution time of less than 40 seconds, for instance, jobs using Cloud Functions.
Don't enable canarying if you want a faster snapshot-triggering cycle.
To configure the Debugger agent to not canary snapshots and logpoints, go to the installation instructions for the Google Cloud platform you're using.
App Engine
Use npm to install the package:
npm install --save @google-cloud/debug-agent
Enable the agent at the top of your app's main script or entry point (but after
@google/cloud-trace
if you are also using it):To debug with canarying enabled:
require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
To debug with canarying not enabled, set
enableCanary
tofalse
:require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
The debugger is now ready for use with your app.
To have the Debug page in the Google Cloud console automatically display source code matching the deployed app, see Selecting source code automatically.
Google Kubernetes Engine
GCLOUD
To enable Debugger using gcloud
, complete the following steps:
Create your cluster with one of the following access scopes:
https://www.googleapis.com/auth/cloud-platform
grants your cluster access to all Google Cloud APIs.https://www.googleapis.com/auth/cloud_debugger
grants your cluster access to only the Debugger API. Use this access scope to harden your cluster's security.
gcloud container clusters create example-cluster-name \ --scopes=https://www.googleapis.com/auth/cloud_debugger
Add the following line to your
Dockerfile
to add the Debugger agent:RUN npm install --save @google-cloud/debug-agent
Enable the agent at the top of your app's main script or entry point (but after
@google/cloud-trace
if you are also using it):To debug with canarying enabled:
require('@google-cloud/debug-agent').start({ serviceContext: { service: 'SERVICE', version: 'VERSION', enableCanary: true, } });
To debug with canarying not enabled, set
enableCanary
tofalse
:enableCanary: false
Where:
SERVICE
is a name for your app, such asMyApp
,Backend
, orFrontend
.VERSION
is a version, such asv1.0
,build_147
, orv20170714
.
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 when you deploy your containerized app.
To have the Debug page in the Google Cloud console automatically display source code matching the deployed app, see Selecting source code automatically.
CONSOLE
To enable Debugger by using the Google Cloud console, complete the following steps:
On the Node pools section, select Security, and then select Set access for each API.
Enable Debugger.
Optional: Select Allow full access to all Cloud APIs.
Add the following line to your
Dockerfile
to add the Debugger agent:RUN npm install --save @google-cloud/debug-agent
Enable the agent at the top of your app's main script or entry point (but after
@google/cloud-trace
if you are also using it):To debug with canarying enabled:
require('@google-cloud/debug-agent').start({ serviceContext: { service: 'SERVICE', version: 'VERSION', enableCanary: true, } });
To debug with canarying not enabled, set
enableCanary
tofalse
:enableCanary: false
Where:
SERVICE
is a name for your app, such asMyApp
,Backend
, orFrontend
.VERSION
is a version, such asv1.0
,build_147
, orv20170714
.
We recommend setting these from environment variables so you do not need to change the source code with each deployment.
Compute Engine
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
Use npm to install the package:
npm install --save @google-cloud/debug-agent
Enable the agent at the top of your app's main script or entry point (but after
@google/cloud-trace
if you are also using it):To debug with canarying enabled:
require('@google-cloud/debug-agent').start({ serviceContext: { service: 'SERVICE', version: 'VERSION', enableCanary: true, } });
To debug with canarying not enabled, set
enableCanary
tofalse
:enableCanary: false
Where:
SERVICE
is a name for your app, such asMyApp
,Backend
, orFrontend
.VERSION
is a version, such asv1.0
,build_147
, orv20170714
.
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 Google Cloud console automatically display source code matching the deployed app, see Selecting Source Code Automatically.
Cloud Run and Cloud Run for Anthos
Use npm to install the package:
npm install --save @google-cloud/debug-agent
Enable the agent at the top of your app's main script or entry point (but after
@google/cloud-trace
if you are also using it):To debug with canarying enabled:
require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
To debug with canarying not enabled, set
enableCanary
tofalse
:enableCanary: false
The debugger is now ready for use when you deploy your app.
Local and elsewhere
Use npm to install the package:
npm install --save @google-cloud/debug-agent
Download service account credentials.
To use the Cloud Debugger agent for Node.js on machines not hosted by Google Cloud, the agent must use a Google Cloud service account credentials to authenticate with the Cloud Debugger Service.
Use the Google Cloud console Service Accounts page to create a credentials file for an existing or new service account. The service account must have at least the
Cloud Debugger Agent
role.Configure and enable the agent with the downloaded credentials:
To debug with canarying enabled:
require('@google-cloud/debug-agent').start({ projectId: 'your-project-id', keyFilename: '/path/to/key.json', serviceContext: { service: 'SERVICE', version: 'VERSION', enableCanary: true, } });
To debug with canarying not enabled, set
enableCanary
tofalse
:enableCanary: false
Where:
SERVICE
is a name for your app, such asMyApp
,Backend
, orFrontend
.VERSION
is a version, such asv1.0
,build_147
, orv20170714
.
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 Google Cloud console can display local source files, without upload, for local development. See Selecting Source Code Manually.