Python Cloud Debugger Agent

Google Cloud Debugger for Python 2.7.

Overview

Cloud Debugger (also known as Stackdriver Debugger) lets you inspect the state of a running cloud application, at any code location, without stopping or slowing it down. It is not your traditional process debugger but rather an always on, whole app debugger taking snapshots from any instance of the app.

Cloud Debugger is safe for use with production apps or during development. The Python debugger agent only few milliseconds to the request latency when a debug snapshot is captured. In most cases, this is not noticeable to users. Furthermore, the Python debugger agent does not allow modification of application state in any way, and has close to zero impact on the app instances.

Cloud Debugger attaches to all instances of the app providing the ability to take debug snapshots and add logpoints. A snapshot captures the call-stack and variables from any one instance that executes the snapshot location. A logpoint writes a formatted message to the application log whenever any instance of the app executes the logpoint location.

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

Cloud Debugger consists of 3 primary components:

The Python debugger agent (this repo implements one for CPython 2.7, and an experimental one for CPython 3.6).
Cloud Debugger service storing and managing snapshots/logpoints. Explore the API's using APIs Explorer.
User interface, including a command line interface gcloud debug and a Web interface on Google Cloud Console. See the online help on how to use Google Cloud Console Debug page.

Getting Help

StackOverflow: http://stackoverflow.com/questions/tagged/google-cloud-debugger
Send email to: Cloud Debugger Feedback
Send Feedback from Google Cloud Console

Installation

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:

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

Note that the build script assumes some dependencies. To install these dependencies on Debian, run this command:

sudo apt-get -y -q --no-install-recommends install \
    curl ca-certificates gcc build-essential cmake \
    python python-dev libpython2.7 python-setuptools

Python 3

There is experimental support for Python 3.6. Python 3.0 to 3.5 are not supported, and newer versions have not been tested.

To build, the python3.6 and python3.6-dev packages are additionally needed. If Python 3.6 is not the default version of the 'python' command on your system, run the build script as PYTHON=python3.6 ./build.sh.

Setup

Google Cloud Platform

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 Python debugger agent authenticate with the machine account of the Virtual Machine.

It is possible to use the Python debugger agent without it. Please see the next section for details.
Install the Python debugger agent as explained in the Installation section.

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.enable()
except ImportError:
  pass

Option B: run the debugger agent as a module:

python -m googleclouddebugger -- myapp.py

Service Account

To use the Python debugger agent on machines not hosted by Google Cloud Platform, the agent must use a Google Cloud Platform service-account credentials to authenticate with the Cloud Debugger Service.

Use the Google 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. If you don't have a Google Cloud Platform project, you can create one for free on Google Cloud Console.

Once you have the service-account JSON file, deploy it alongside the Python debugger agent.

Once you have the service account, please note the service account e-mail, project ID and project number.

Then, enable the debugger agent using one of these two options:

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

# Attach Python Cloud Debugger
try:
  import googleclouddebugger
  googleclouddebugger.enable(
      enable_service_account_auth=True,
      project_id='my-gcp-project-id',
      project_number='123456789',
      service_account_json_file='/opt/cdbg/gcp-svc.json')
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_json_file=/opt/cdbg/gcp-svc.json \
    -- \
    myapp.py

Django Web Framework

You can use the Cloud Debugger to debug Django web framework applications.

The best way to enable the Cloud Debugger with Django is to add the following code fragment to your manage.py file:

# Attach the Python Cloud debugger (only the main server process).
if os.environ.get('RUN_MAIN') or '--noreload' in sys.argv:
  try:
    import googleclouddebugger
    googleclouddebugger.enable()
  except ImportError:
    pass

Alternatively, you can pass the --noreload flag when running the Django manage.py and use any one of the option A and B listed earlier. Note that using the --noreload flag disables the autoreload feature in Django, which means local changes to files will not be automatically picked up by Django.

gcbirzan/cloud-debug-python