Setting Up Stackdriver Debugger for Python applications on Google Compute Engine

You can use Stackdriver Debugger with any Python 2.7 application running on a Google Compute Engine instance. We recommend that you enable it on all running instances of your application.

This page covers the setup steps required for most developers. Additional details and setup options (such as building from source and using a service account) are covered at http://github.com/GoogleCloudPlatform/cloud-debug-python/.

Requirements

Google Stackdriver Debugger works with Compute Engine instances running:

  • A 64-bit Debian Linux image
  • Python 2.7

For instructions on creating a Compute Engine instance, refer to Creating and Starting an Instance in the Google Compute Engine documentation.

Download the agent

The Stackdriver Debugger agent is a lightweight binary that starts with your application and communicates with the Stackdriver Debugger backend while the application is running.

The easiest way to install the Python Stackdriver Debugger is with PyPI:

pip install google-python-cloud-debugger

Alternatively, you can download the .egg package from GitHub and install the debugger agent with:

easy_install google_python_cloud_debugger-py2.7-linux-x86_64.egg

You can also build the agent from source code (OS dependencies are listed in build.sh script):

git clone https://github.com/GoogleCloudPlatform/cloud-debug-python.git
cd cloud-debug-python/src/
./build.sh
easy_install dist/google_python_cloud_debugger-*.egg

Set up the agent

There are two ways to enable the agent in your application.

  • If you'd prefer to change the code than change the way your program is invoked, add the following lines to the beginning of your main() function:

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

Or...

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

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

Where, in both cases:

  • [VERSION] is the app version (e.g. the build ID). The Cloud Platform Console displays the running version as [MODULE] - [VERSION]. Example values: v1.0, build_147, or v20160520.

  • [MODULE] is the name of your application or service. This, along with the version, is used to identify your application in the Cloud Platform Console. Examples: MyApp, Backend, or Frontend.

Generate the source context file

The source context file contains information about the version of the source code used to build your application. The Debug page in the Cloud Platform Console uses this information to display the correct version of the source.

To generate the source context file, run the following in the root directory of your local Git repository.

gcloud debug source gen-repo-info-file --output-directory=[MODULE_PACKAGE_DIR]

Where [MODULE_PACKAGE_DIR] is the top level of your Python module package. For example:

--output-directory="./my-python-app/"

Then, deploy (or redeploy) your application to your Compute Engine instance.

Using Stackdriver Debugger

After you have set up Stackdriver Debugger for use in your environment and you have started your application, you can open the Debug page in the Cloud Platform Console. See Using Stackdriver Debugger for more information.

Send feedback about...

Stackdriver Debugger Documentation