Google Cloud Debugger for Python 2.7.

The Cloud Debugger lets you inspect the state of an application at any code location without stopping or slowing it down. The debugger makes it easier to view the application state without adding logging statements.

You can use the Cloud Debugger on both production and staging instances of your application. The debugger never pauses the application for more than a few milliseconds. In most cases, this is not noticeable by users. The Cloud Debugger gives a read-only experience. Application variables can't be changed through the debugger.

The Cloud Debugger attaches to all instances of the application. The call stack and the variables come from the first instance to take the snapshot.

The Python Cloud Debugger is only supported on Linux at the moment. It was tested on Debian Linux, but it should work on other distributions as well.

The Cloud Debugger consists of 3 primary components:

1. The debugger agent. This repo implements one for Python 2.7.
2. Cloud Debugger backend that stores the list of snapshots for each debuggee. You can explore the API using the APIs Explorer.
3. User interface for the debugger implemented using the Cloud Debugger API. Currently the only option for Python is the Google Developers Console. The UI requires that the source code is submitted to Google Cloud Repo. More options (including browsing local source files) are coming soon.

This document only focuses on the Python debugger agent. Please see the this page for explanation how to debug an application with the Cloud Debugger.

1. StackOverflow: http://stackoverflow.com/questions/tagged/google-cloud-debugger
2. Google Group: cdbg-feedback@google.com

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

pip install google-python-cloud-debugger

Alternatively, download the egg package from Releases 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

1. First, make sure that you created the VM with this option enabled:

   Allow API access to all Google Cloud services in the same project.

   This option lets the debugger agent authenticate with the machine account of the Virtual Machine.

   It is possible to use Python Cloud Debugger without it. Please see the next section for details.

2. Install the debugger agent as explained in the Installation section.

3. Enable the debugger in your application using one of the two options:

   Option A: add this code to the beginning of your main() function:

   # Attach Python Cloud Debugger
   try:
     import googleclouddebugger
     googleclouddebugger.AttachDebugger()
   except ImportError:
     pass

   Option B: run the debugger agent as a module:

   python -m googleclouddebugger -- myapp.py
   

Service account authentication lets you run the debugger agent on any Linux machine, including outside of Google Cloud Platform. The debugger agent authenticates against the backend with the service account created in Google Developers Console. If your application runs on Google Compute Engine, metadata service authentication is an easier option.

The first step for this setup is to create the service account in .p12 format. Please see this page for detailed instructions. If you don't have a Google Cloud Platform project, you can create one for free on Google Developers Console.

Once you have the service account, please note the service account e-mail, project ID and project number. Then copy the .p12 file to all the machines that run your application.

Then, enable the debugger agent in a similary way as described in the previous section:

Option A: add this code to the beginning of your main() function:

# Attach Python Cloud Debugger
try:
  import googleclouddebugger
  googleclouddebugger.AttachDebugger(
      enable_service_account=True,
      project_id='my-gcp-project-id',
      project_number='123456789',
      service_account_email='123@developer.gserviceaccount.com',
      service_account_p12_file='/opt/cdbg/gcp.p12')
except ImportError:
  pass

Option B: run the debugger agent as a module:

python \
    -m googleclouddebugger \
    --enable_service_account_auth=1 \
    --project_id=my-gcp-project-id \
    --project_number=123456789 \
    --service_account_email=123@developer.gserviceaccount.com \
    --service_account_p12_file=/opt/cdbg/gcp.p12 \
    -- \
    myapp.py