Setting Up Stackdriver Debugger for Python

Alpha

This is an alpha release of the Stackdriver Debugger agent for Python 3.7. This library might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy.

Note: Stackdriver Debugger is generally available for Python 2.7.

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.

App Engine standard environment

If you are using Python 2.7, the debugger is enabled by default and no configuration is required.

If you are using Python 3.7, you must manually enable the debugger agents by following the instructions for App Engine flexible environment.

The Debug page in the GCP Console automatically displays the deployed files matching the app source code. To learn more about source code matching, see Selecting Source Code Automatically.

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 2.7 or 3.6

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

   runtime: python
   env: flex
   
   # The Python runtime uses Python 3.6 by default.
   # To use Python 2.7 add the following lines.
   # runtime_config:
   #   python_version: 2
   

   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
   

The debugger is now ready for use with your app.

To have the Debug page in the GCP Console automatically display source code matching the deployed app, see Selecting Source Code Automatically.

Google Kubernetes Engine

1. Create your cluster, with one of the following access scopes:
   • https://www.googleapis.com/auth/cloud-platform
   • https://www.googleapis.com/auth/cloud_debugger
   Note: You cannot change the access scopes of a cluster after creation.

   To create a cluster using gcloud, do the following:

   1. (Optional) Update gcloud to the latest version:

      gcloud components update

   2. Set your default project ID:

      gcloud config set project [PROJECT_ID]

   3. If you're working with zonal clusters, set your default compute zone:

      gcloud config set compute/zone [COMPUTE_ZONE]

   4. If you're working with regional clusters, set your default compute region:

      gcloud config set compute/region [COMPUTE_REGION]

   5. Issue the create command:

      gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform

   For more detailed information on creating a cluster, see Creating a cluster.

2. Follow the instructions for Compute Engine.

Compute Engine

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

   • A 64-bit Debian Linux image
   • Python 2.7 or 3.7

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 Stackdriver Debugger is with 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
   

   Or... 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 GCP Console Debug page.
     Examples: MyApp, Backend, or Frontend.
   • [VERSION] is the app version (for example, the build ID).
     The GCP 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 GCP Console automatically display source code matching the deployed app see Selecting Source Code Automatically.

Local and Elsewhere

1. Make sure your workstation is running:

   • A 64-bit Debian Linux image
   • Python 2.7 or 3.7

2. Download the debugger agent.

   The easiest way to install the Python Stackdriver Debugger is with pip

   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 Platform, the agent must use GCP service-account credentials to authenticate with the Stackdriver Debugger Service.

   Use the GCP 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
   

   Or... 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 GCP Console Debug page.
     Examples: MyApp, Backend, or Frontend.
   • [VERSION] is the app version (for example, the build ID).
     The GCP 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 GCP 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.

Troubleshooting

The google-python-cloud-debugger Python package requires the python2.7-dev Linux package and the setuptools and wheel Python packages. While these packages are typically installed when you install pip with all suggested dependencies, missing some of them can cause the following errors.

1. ImportError: No module named setuptools

   The setuptools Python package needs to be installed (for example, pip install setuptools).

2. invalid command 'bdist_wheel' or Failed building wheel for '...'

   The wheel Python package needs to be installed (for example, pip install wheel).

3. ImportError: libpython2.7.so.1.0: cannot open shared object file: No such file or directory

   The python2.7-dev Linux package needs to be installed (for example, apt-get install python2.7-dev).