Setting up Stackdriver Trace for Python

Alpha

This product or feature is in a pre-release state and might change or have limited support. For more information, see Product launch stages.

You can enable Stackdriver 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

To collect traces, you need to import the Stackdriver exporter and the OpenCensus tracer packages. Your application must also instantiate StackdriverExporter and Tracer objects:

View on GitHub Feedback

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)

    return tracer

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

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

Regardless of your infrastructure, when you don't explicitly set the GCP 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 GCP project ID. For more information, go to Configuration. 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.

Configuring your platform

You can use Trace on GCP and when your application runs outside of GCP.

Running on GCP

When your application is running on GCP, your application is automatically authenticated and you don't need to provide authentication credentials. However, you do need to ensure that your GCP platform has the Stackdriver Trace API access scope enabled.

For the following configurations, the default settings for the access scopes have the Stackdriver Trace API enabled:

• App Engine flexible environment

• App Engine standard environment

• Google Kubernetes Engine

• Compute Engine

If you use custom access scopes, then you must ensure that Stackdriver Trace API access scope enabled. For gcloud users, specify access scopes using the --scopes flag and include the trace.append Stackdriver Trace API access scope. For example, to create a GKE cluster with only the Stackdriver 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

When your application is running outside of GCP, 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.

GCP client libraries use Application default credentials (ADC) to find your application's credentials. You provide these credentials by setting the GOOGLE_APPLICATION_CREDENTIALS environment variable:

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

View on GitHub Feedback

@app.route('/index.html', methods=['GET'])
def index():
    tracer = app.config['TRACER']
    tracer.start_span(name='index')

    # Add up to 1 sec delay, weighted toward zero
    time.sleep(random.random() ** 2)
    result = "Tracing requests"

    tracer.end_span()
    return result

Viewing the traces

After deployment, you can view the traces in the GCP Console Trace Viewer.

Go to the Trace Viewer page

Resources

• OpenCensus
• GitHub: census-instrumentation/opencensus-python
• GitHub: googleapis/google-cloud-python