Trace's Python support is provided by OpenCensus, a set of tracing and application metrics instrumentation libraries that work with multiple backends. You can find the latest details about OpenCensus for Python, along with additional documentation and examples, on its GitHub page.
Installation and configuration
To collect traces, you need to import the Stackdriver exporter and the OpenCensus tracer packages. Your application must also instantiate a Stackdriver exporter and a tracer.
The Stackdriver exporter uses the Application Default Credentials for authentication. You can omit the project ID if your code is running on Google Cloud Platform (GCP):
from opencensus.trace.exporters import 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
Running on Google Cloud Platform
You don't need to provide authentication credentials for instances running on Google Cloud Platform, provided Stackdriver Trace API access scope is enabled on that instance. However, we recommend setting the broadest possible access scope for your instance and then using Cloud Identity and Access Management to restrict access.
App Engine flexible environment
On App Engine flexible environment, the Stackdriver Trace API access scope is enabled by default, and the OpenCensus client library can be used without providing credentials or a project ID.
App Engine standard environment
On App Engine standard environment, the Stackdriver Trace API access scope is enabled by default, and the OpenCensus client library can be used without providing credentials or a project ID.
Google Kubernetes Engine
To use Trace with GKE, add the
trace.append OAuth access scope when you create your cluster.
To create a cluster using
gcloud, do the following:
- (Optional) Update
gcloudto the latest version:
gcloud components update
- Set your default project ID:
gcloud config set project [PROJECT_ID]
- If you're working with zonal clusters, set your default compute zone:
gcloud config set compute/zone [COMPUTE_ZONE]
- If you're working with regional clusters, set your default compute region:
gcloud config set compute/region [COMPUTE_REGION]
- Issue the create command:
gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append
For more detailed information on creating a cluster, see Creating a cluster.
For Compute Engine VM instances, you need to explicitly enable
trace.append Stackdriver Trace API access scope for each VM
instance. When creating a new instance through the
Google Cloud Platform Console,
select the following values in the Identity and API access section
of the Create an instance panel:
- Select Compute Engine default service account for Service account
- Select Allow full access to all Cloud APIs for Access Scopes
To use something other than the Compute Engine default service account see the Creating and enabling service accounts for instances and Running locally and elsewhere sections. The important thing is that the service account you use has the Cloud Trace Agent role.
Running locally and elsewhere
To run Stackdriver Trace outside of GCP you must supply your GCP project ID and appropriate service account credentials directly to OpenCensus client library . Your service account must contain the Cloud Trace agent role. For instructions, see Creating a service account.
Provide a project ID to the OpenCensus as shown in
Installation and configuration.
We recommend that you set the environment variable
GOOGLE_CLOUD_PROJECT to your project ID and modify your
application to read this variable. To set the environment variable, do the
Linux or macOS
GCP client libraries use
Application default credentials (ADC) to find your application's
credentials. You provide credentials to the OpenCensus client library
by setting the
GOOGLE_APPLICATION_CREDENTIALS environment variable:
@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.