Setting Up Stackdriver Debugger for Python

App Engine Standard

The debugger is enabled by default, no configuration is required. The Debug page in the GCP Console will automatically display the deployed files matching the app source code.

To learn more see Selecting Source Code Automatically.

App Engine Flexible

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

    • A 64-bit Debian Linux image
    • Python 2.7
  2. Make sure your app.yaml file contains the following lines:

    runtime: python
    env: flex
    
    runtime_config:
      python_version: 2
    
  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.

    try:
      import googleclouddebugger
      googleclouddebugger.AttachDebugger()
    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.

Kubernetes Engine

  1. Make sure your cluster is created with one of the following access scopes:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger

    Example:

    gcloud container clusters create example-cluster-name \
        --scopes https://www.googleapis.com/auth/cloud-platform
    
  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
  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 PyPI:

    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.AttachDebugger(
        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 (e.g., 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
  2. Download the debugger agent

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

    pip install google-python-cloud-debugger
    
  3. Download service account credentials.
    To use the Python debugger agent on machines not hosted by Google Cloud Platform, the agent must use a 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 Cloud Debugger Agent role to be accepted by the Cloud Debugger Service.

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

    Place the service-account JSON file alongside the Python debugger agent.

  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(
          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
    

    Or... if you can't change the code, 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
    

    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 (e.g., 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.

The Debug page in the GCP Console can display local source files, without upload, for local development. See Selecting Source Code Manually.

Send feedback about...

Stackdriver Debugger Documentation