Overview
This page describes how to configure your environment and your
Python 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 Python 3 on the following compute environments:
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
The Debugger agent for Python can use canary snapshots and logpoints every time you set a snapshot or logpoint.
The Debugger agent canaries snapshots and logpoints to protect large jobs from any potential bug in the Debugger agent which can take the entire job down when a snapshot or a logpoint is applied.
To mitigate this, Debugger canaries snapshots and logpoints on a subset of your running instances each time they are set. After Debugger verifies the snapshot or logpoint does not adversely affect your running instances, Debugger then applies the snapshot or logpoint 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 standard environment
Python 3.7 or Python 3.8
If you are using Python 3.7 or Python 3.8, you must manually enable the Debugger agent by performing the following steps:
Make sure your
app.yaml
file contains the following lines:runtime: python37 or runtime: python38
Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using the Django web framework (version 1.* only).To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( breakpoint_enable_canary=True ) except ImportError: pass
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
Add
google-python-cloud-debugger
torequirements.txt
.To have the Debug page in the Cloud Console automatically display source code matching the deployed app, go to Selecting source code automatically.
The Debugger is now ready for use with your app.
App Engine flexible environment
You can use the Debugger with the App Engine Python runtime or a custom runtime.
Make sure your App Engine Flexible VM instances are running:
- A 64-bit Debian Linux image
- Python 3
Make sure your
app.yaml
file contains the following lines:runtime: python env: flex
If you are using a Custom Runtime, use
runtime: custom
.Add
google-python-cloud-debugger
torequirements.txt
.Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using the Django web framework (version 1.* only).To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( breakpoint_enable_canary=True ) except ImportError: pass
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.
The Debugger is now ready for use with your app.
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 Debugger package to your app:
If you use a
requirements.txt
file, add the following line:google-python-cloud-debugger
If you use a
Dockerfile
, add the following line:RUN pip install google-python-cloud-debugger
Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using the Django web framework:To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( breakpoint_enable_canary=True ) except ImportError: pass
To debug with canarying NOT enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
On the Debug page, select the location of the source code. To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.
The Debugger is now ready to use.
CONSOLE
To enable Debugger using the console, complete the following steps:
After selecting your cluster type, click More options from the Node pools pane:
Select one of the following from the Security pane:
Allow full access to all Cloud APIs.
Allow access for each API and then select Enabled for Cloud Debugger.
Add the Debugger package to your app:
If you use a
requirements.txt
file, add the following line:google-python-cloud-debugger
If you use a
Dockerfile
, add the following line:RUN pip install google-python-cloud-debugger
Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using the Django web framework:To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( breakpoint_enable_canary=True ) except ImportError: pass
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
On the Debug page, select the location of the source code. To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.
The Debugger is now ready to use.
Compute Engine
Make sure your Compute Engine VM instances are running:
- A 64-bit Debian Linux image
- Python 3
Make sure your Compute Engine VM 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
Download the Debugger agent.
The easiest way to install the Python Debugger is with [
pip
][pip]:pip install google-python-cloud-debugger
Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using the Django web framework.To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( module='[MODULE]', version='[VERSION]' breakpoint_enable_canary=True ) except ImportError: pass
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
If you can't change the code, run the Debugger agent as a module.
To debug with canarying enabled:
python -m googleclouddebugger \ --module=[MODULE] \ --version=[VERSION] \ --breakpoint_enable_canary=True -- \ myapp.py
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
Replace the placeholders in the command as follows:
[MODULE]
is the name of your app.
This, along with the version, is used to identify the debug target in the Cloud Console Debug page.
Examples:MyApp
,Backend
, orFrontend
.[VERSION]
is the app version (for example, the build ID).
The Cloud Console Debug page displays the running version as[MODULE] - [VERSION]
.
Example values:v1.0
,build_147
, orv20170714
.
The Debugger is now ready for use with your app.
To have the Debug page in the Cloud Console automatically display source code matching the deployed app see Selecting source code automatically.
Cloud Run and Cloud Run for Anthos on Google Cloud
Python package.
If you use a
requirements.txt
file, add the following line:google-python-cloud-debugger
If you do not, add the following line to your
Dockerfile
:RUN pip install google-python-cloud-debugger
Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using the Django web framework:To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( breakpoint_enable_canary=True ) except ImportError: pass
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
On the Debug page, select the location of the source code. To have the Debug page in the Cloud Console automatically display source code matching the deployed app, see Selecting source code automatically.
The Debugger is now ready to use.
Local and elsewhere
Make sure your workstation is running:
- A 64-bit Debian Linux image
- Python 3
Download the Debugger agent.
The easiest way to install the Python Debugger is with [
pip
][pip]{: .external}:pip install google-python-cloud-debugger
Download service account credentials.
To use the Cloud Debugger agent for Python on machines not hosted by Google Cloud, the agent must use Google Cloud service-account credentials to authenticate with the Cloud Debugger Service.
Use the 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.Place the service-account JSON file alongside the Cloud Debugger agent for Python.
Add the following lines as early as possible in your initialization code, such as in your main function, or in
manage.py
when using Django Web Framework.To debug with canarying enabled:
try: import googleclouddebugger googleclouddebugger.enable( module='[MODULE]', version='[VERSION]', breakpoint_enable_canary=True service_account_json_file='/opt/cdbg/gcp-svc.json') except ImportError: pass
To debug with canarying NOT enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
If you can't change the code, run the Debugger agent as a module.
To debug with canarying enabled:
python \ -m googleclouddebugger \ --module=[MODULE] \ --version=[VERSION] \ --breakpoint_enable_canary=True --service_account_json_file=/opt/cdbg/gcp-svc.json \ -- \ myapp.py
To debug with canarying not enabled, set the
breakpoint_enable_canary
parameter toFalse
:breakpoint_enable_canary=False
Replace the placeholders in the command as follows:
[MODULE]
is the name of your app.
This, along with the version, is used to identify the debug target in the Cloud Console Debug page.
Examples:MyApp
,Backend
, orFrontend
.[VERSION]
is the app version (for example, the build ID).
The Cloud Console Debug page displays the running version as[MODULE] - [VERSION]
.
Example values:v1.0
,build_147
, orv20170714
.- The
GOOGLE_APPLICATION_CREDENTIALS
environment variable can be used instead of specifyingservice_account_json_file
.
The Debugger is now ready for use with your app.
The Debug page in the Cloud Console can display local source files, without upload, for local development. See Selecting source code manually.