Name: cloud-debug-python
Owner: Google Cloud Platform
Description: Python Cloud Debugger
Created: 2015-10-02 18:58:12.0
Updated: 2018-05-22 07:07:18.0
Pushed: 2018-04-13 16:48:00.0
Homepage: https://cloud.google.com/tools/cloud-debugger/
Size: 358
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
Google Cloud Debugger for Python 2.7.
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:
gcloud debug
and a Web
interface on Google Cloud Console. See the online help on how to use Google
Cloud Console Debug page.The easiest way to install the Python Cloud Debugger is with PyPI:
install google-python-cloud-debugger
Alternatively, download the egg package from Releases and install the debugger agent with:
_install google_python_cloud_debugger-py2.7-linux-x86_64.egg
You can also build the agent from source code:
clone https://github.com/GoogleCloudPlatform/cloud-debug-python.git
loud-debug-python/src/
ild.sh
_install dist/google_python_cloud_debugger-*.egg
Note that the build script assumes some dependencies. To install these dependencies on Debian, run this command:
apt-get -y -q --no-install-recommends install \
curl ca-certificates gcc build-essential cmake \
python python-dev libpython2.7 python-setuptools
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
.
The Python agent is not regularly tested on Alpine Linux, and support will be on a best effort basis. The Dockerfile shows how to build a minimal image with the agent installed.
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:
tach Python Cloud Debugger
port googleclouddebugger
ogleclouddebugger.enable(module='[MODULE]', version='[VERSION]')
pt ImportError:
ss
Option B: run the debugger agent as a module:
python \ -m googleclouddebugger --module=[MODULE] --version=[VERSION] -- \ myapp.py
Note: This option does not work well with tools such as
multiprocessing
or gunicorn
. These tools spawn workers in separate
processes, but the debugger does not get enabled on these worker processes.
Please use Option A instead.
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 UI.
Example values: MyApp
, Backend
, or Frontend
.
[VERSION]
is the app version (for example, the build ID). The UI
displays the running version as [MODULE] - [VERSION]
.
Example values: v1.0
, build_147
, or v20170714
.
To use the Python debugger agent on machines not hosted by Google Cloud Platform, you must set up credentials to authenticate with Google Cloud APIs. By default, the debugger agent tries to find the Application Default Credentials on the system. This can either be from your personal account or a dedicated service account.
Set up Application Default Credentials through gcloud.
ud auth application-default login
Follow the rest of the steps in the GCP section.
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.
Once you have the service account credentials JSON file, deploy it alongside the Python debugger agent.
Set the GOOGLE_APPLICATION_CREDENTIALS
environment variable.
rt GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
Alternatively, you can provide the path to the credentials file directly to the debugger agent.
Option A:
tach Python Cloud Debugger
port googleclouddebugger
ogleclouddebugger.enable(
module='[MODULE]',
version='[VERSION]',
service_account_json_file='/path/to/credentials.json')
pt ImportError:
ss
Option B:
python \ -m googleclouddebugger \ --module=[MODULE] \ --version=[VERSION] \ --service_account_json_file=/path/to/credentials.json \ -- \ myapp.py
Follow the rest of the steps in the GCP section.
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:
tach the Python Cloud debugger (only the main server process).
s.environ.get('RUN_MAIN') or '--noreload' in sys.argv:
y:
import googleclouddebugger
googleclouddebugger.enable(module='[MODULE]', version='[VERSION]')
cept 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.
The agent offers various flags to configure its behavior. Flags can be specified as keyword arguments:
leclouddebugger.enable(flag_name='flag_value')
or as command line arguments when running the agent as a module:
on -m googleclouddebugger --flag_name=flag_value -- myapp.py
The following flags are available:
module
: A name for your app. This, along with the version, is used to identify
the debug target in the UI.
Example values: MyApp
, Backend
, or Frontend
.
version
: A version for your app. The UI displays the running version as
[MODULE] - [VERSION]
.
If not provided, the UI will display the generated debuggee ID instead.
Example values: v1.0
, build_147
, or v20170714
.
service_account_json_file
: Path to JSON credentials of a service account to use for
authentication. If not provided, the agent will fall back to Application Default Credentials
which are automatically available on machines hosted on GCP, or can be set via
gcloud auth application-default login
or the GOOGLE_APPLICATION_CREDENTIALS
environment variable.