Setting up Cloud Trace for Python

You can enable Cloud Trace for Python applications by using OpenCensus. OpenCensus is a set of instrumentation libraries for collecting trace and metric data that work with multiple backends. For the latest details about OpenCensus for Python, along with additional documentation and examples, go to census-instrumentation/opencensus-python.

Installation and configuration

Install the OpenCensus packages using pip:

pip install opencensus
pip install opencensus-ext-stackdriver

Update your application to import the Stackdriver exporter and the OpenCensus tracer packages. Your application must also instantiate StackdriverExporter and Tracer objects:

from opencensus.ext.stackdriver import trace_exporter as stackdriver_exporter
import opencensus.trace.tracer


def initialize_tracer(project_id):
    exporter = stackdriver_exporter.StackdriverExporter(
        project_id=project_id
    )
    tracer = opencensus.trace.tracer.Tracer(
        exporter=exporter,
        sampler=opencensus.trace.tracer.samplers.AlwaysOnSampler()
    )

    return tracer

For more information on the exporter, see OpenCensus Tracing.

If you are running on Google Cloud infrastructure, then you don't need to set project_id to your Google Cloud project ID. If you don't set this field, the client library for Python automatically gathers this data from a Google Cloud metadata server.

If you aren't running on Google Cloud infrastructure, then you must supply your Google Cloud project ID to your application.

Regardless of your infrastructure, when you don't explicitly set the Google Cloud project ID, the google-cloud Python library, which is invoked by OpenCensus, automatically determines if the environment variable GOOGLE_CLOUD_PROJECT is set, and if so, the library uses the value of GOOGLE_CLOUD_PROJECT as your Google Cloud project ID. For more information on authentication when using client libraries, see Authentication. For general information, see Getting started with authentication.

To set the environment variable, do the following:

Linux or macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

Performance optimization

To reduce the performance impact of reporting trace data, have this data sent by a background process. To configure background reporting of trace data, include transport=AsyncTransport when initializing the StackdriverExporter.

Configure your platform

You can use Cloud Trace on Google Cloud and other platforms.

Running on Google Cloud

When your application is running on Google Cloud, you don't need to provide authentication credentials in the form of a service account to the client library. However, you do need to ensure that your Google Cloud platform has the Cloud Trace API access scope enabled.

For a list of supported Google Cloud environments, see Environment support.

For the following configurations, the default access-scope settings enable the Cloud Trace API:

  • App Engine flexible environment

  • App Engine standard environment

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

If you use custom access scopes, then you must ensure that Cloud Trace API access scope is enabled:

  • For information about how to configure the access scopes for your environment by using the Google Cloud console, see Configuring your Google Cloud project.

  • For gcloud users, specify access scopes using the --scopes flag and include the trace.append Cloud Trace API access scope. For example, to create a GKE cluster with only the Cloud Trace API enabled, do the following:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Running locally and elsewhere

If your application is running outside of Google Cloud, then you must provide authentication credentials in the form of a service account to the client library. The service account must contain the Cloud Trace agent role. For instructions, see Creating a service account.

Google Cloud client libraries use Application Default Credentials (ADC) to find your application's credentials.

You can provide these credentials in one of three ways:

  • Run gcloud auth application-default login

  • Place the service account in a default path for your operating system. The following lists the default paths for Windows and Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path to your service account:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Sample Flask application

For a sample Python application that utilizes Flask, see the Trace Quickstart.

For details on how the application was instrumented to capture Trace data, see Instrumentation.

Viewing the traces

After deployment, you can view the traces in the Google Cloud console Trace Viewer.

Go to the Trace Viewer page

Troubleshooting

For information on troubleshooting issues with Cloud Trace, go to the Troubleshooting page.

Resources