Setting Up Stackdriver Debugger for Python

Alpha

This library is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

This page describes how to configure your environment and your Python application to use Stackdriver Debugger. For some environments, you must explicitly specify the access scope to let the Stackdriver Debugger agent send data. We recommend setting the broadest possible access scope and then using Cloud 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.

Before you begin

To begin using Debugger, ensure the Debugger API is enabled.
Enable Debugger API

Note: Debugger is free to use. However, you need a Google Cloud project with billing enabled before you can use Debugger.

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 agents by performing the following steps:

1. Make sure your app.yaml file contains the following lines:

   runtime: python37
   or
   runtime: python38
   

2. 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).

   try:
     import googleclouddebugger
     googleclouddebugger.enable()
   except ImportError:
     pass
   

3. Add google-python-cloud-debugger to requirements.txt.

4. 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 Custom Runtime.

1. Make sure your App Engine Flexible VM instances are running:

   • A 64-bit Debian Linux image
   • Python 3

2. Make sure your app.yaml file contains the following lines:

   runtime: python
   env: flex
   

   If you are using a Custom Runtime, use runtime: custom.

3. Add google-python-cloud-debugger to requirements.txt.

4. 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).

   try:
     import googleclouddebugger
     googleclouddebugger.enable()
   except ImportError:
     pass
   

5. 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:

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

   Note: You cannot change the access scopes of a cluster after creation.

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

3. 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:

   try:
     import googleclouddebugger
     googleclouddebugger.enable()
   
   except ImportError:
     pass
   

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:

1. After selecting your cluster type, click More options from the Node pools pane:

   

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

Compute Engine

1. Make sure your Compute Engine VM instances are running:

   • A 64-bit Debian Linux image
   • Python 3

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

3. Download the Debugger agent.

   The easiest way to install the Python Debugger is with [pip][pip]:

   pip install google-python-cloud-debugger
   

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
       module='[MODULE]',
       version='[VERSION]'
     )
   except ImportError:
     pass
   

   If you can't change the code, run the Debugger agent as a module:

   python -m googleclouddebugger \
         --module=[MODULE] \
         --version=[VERSION] \
         -- \
         myapp.py
   

   Where, in both cases:

   • [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, or Frontend.
   • [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, or v20170714.

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

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

2. 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:

   try:
     import googleclouddebugger
     googleclouddebugger.enable()
   
   except ImportError:
     pass
   

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

1. Make sure your workstation is running:

   • A 64-bit Debian Linux image
   • Python 3

2. Download the Debugger agent.

   The easiest way to install the Python Debugger is with [pip][pip]{: .external}:

   pip install google-python-cloud-debugger
   

3. Download service account credentials.
   To use the Stackdriver Debugger agent for Python on machines not hosted by Google Cloud, the agent must use Google Cloud service-account credentials to authenticate with the Stackdriver 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 Stackdriver Debugger Agent role.

   Place the service-account JSON file alongside the Stackdriver Debugger agent for Python.

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
         module='[MODULE]',
         version='[VERSION]'
         service_account_json_file='/opt/cdbg/gcp-svc.json')
   except ImportError:
     pass
   

   If you can't change the code, run the Debugger agent as a module:

   python \
       -m googleclouddebugger \
       --module=[MODULE] \
       --version=[VERSION] \
       --service_account_json_file=/opt/cdbg/gcp-svc.json \
       -- \
       myapp.py
   

   Where, in both cases:

   • [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, or Frontend.
   • [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, or v20170714.
   • The GOOGLE_APPLICATION_CREDENTIALS environment variable can be used instead of specifying service_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.

Note: You can find the Debugger agent's code and documentation on GitHub.