OpenCensus for Python - A stats collection and distributed tracing framework

Census for Python. Census provides a framework to measure a server's resource usage and collect performance stats. This repository contains Python related utilities and supporting software needed by Census.

API Documentation

Installation & basic usage

Install the opencensus-trace package using pip or pipenv:
```
pip install opencensus
pipenv install opencensus
```

Initialize a tracer for your application:

from opencensus.trace import tracer as tracer_module

tracer = tracer_module.Tracer()

Usage

You can collect traces using the Tracer context manager:

from opencensus.trace import tracer as tracer_module

# Initialize a tracer, by default using the `PrintExporter`
tracer = tracer_module.Tracer()

# Example for creating nested spans
with tracer.span(name='span1') as span1:
    do_something_to_trace()
    with span1.span(name='span1_child1') as span1_child1:
        do_something_to_trace()
    with span1.span(name='span1_child2') as span1_child2:
        do_something_to_trace()
with tracer.span(name='span2') as span2:
    do_something_to_trace()

Census will collect everything within the with statement as a single span.

Alternatively, you can explicitly start and end a span:

from opencensus.trace import tracer as tracer_module

# Initialize a tracer, by default using the `PrintExporter`
tracer = tracer_module.Tracer()

tracer.start_span(name='span1')
do_something_to_trace()
tracer.end_span()

Customization

Samplers

You can specify different samplers when initializing a tracer, default is using AlwaysOnSampler, the other options are AlwaysOffSampler and ProbabilitySampler

from opencensus.trace.samplers import probability
from opencensus.trace import tracer as tracer_module

# Sampling the requests at the rate equals 0.5
sampler = probability.ProbabilitySampler(rate=0.5)
tracer = tracer_module.Tracer(sampler=sampler)

Exporters

You can choose different exporters to send the traces to. By default, the traces are printed to stdout in JSON format. Other options include writing to a file, sending to Python logging, or reporting to Stackdriver.

This example shows how to configure Census to save the traces to a file:

from opencensus.trace.exporters import file_exporter
from opencensus.trace.tracers import context_tracer

exporter = file_exporter.FileExporter(file_name='traces')
tracer = context_tracer.ContextTracer(exporter=exporter)

This example shows how to report the traces to Stackdriver Trace:

from opencensus.trace.exporters import stackdriver_exporter
from opencensus.trace import tracer as tracer_module

exporter = stackdriver_exporter.StackdriverExporter(
    project_id='your_cloud_project')
tracer = tracer_module.Tracer(exporter=exporter)

Propagators

You can specify the propagator type for serializing and deserializing the SpanContext and its headers. There are currently two built in propagators: GoogleCloudFormatPropagator and TextFormatPropagator.

This example shows how to use the GoogleCloudFormatPropagator:

from opencensus.trace.propagation import google_cloud_format

propagator = google_cloud_format.GoogleCloudFormatPropagator()

# Deserialize
span_context = propagator.from_header(header)

# Serialize
header = propagator.to_header(span_context)

Blacklist Paths

You can specify which paths you do not want to trace by configuring the blacklist paths.

This example shows how to configure the blacklist to ignore the _ah/health endpoint for a Flask application:

from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware

app = flask.Flask(__name__)

blacklist_paths = ['_ah/health']
middleware = FlaskMiddleware(app, blacklist_paths=blacklist_paths)

For Django, you can configure the blacklist in the OPENCENSUS_PARAMS in settings.py:

OPENCENSUS_PARAMS: {
    ...
    'BLACKLIST_PATHS': ['_ah/health',],
}

Note

By default the health check path for the App Engine flexible environment is not traced, but you can turn it on by excluding it from the blacklist setting.

Framework Integration

Census supports integration with popular web frameworks including Django, Flask, Pyramid, and Webapp2. When the application receives a HTTP request, the tracer will automatically generate a span context using the trace information extracted from the request headers, and propagated to the child spans.

Flask

In your application, use the middleware to wrap your app and the requests will be automatically traced.

from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware

app = flask.Flask(__name__)

# You can also specify the sampler, exporter, propagator in the middleware,
# default is using `AlwaysOnSampler` as sampler, `PrintExporter` as exporter,
# `GoogleCloudFormatPropagator` as propagator.
middleware = FlaskMiddleware(app)

Django

For tracing Django requests, you will need to add the following line to the MIDDLEWARE_CLASSES section in the Django settings.py file.

MIDDLEWARE_CLASSES = [
    ...
    'opencensus.trace.ext.django.middleware.OpencensusMiddleware',
]

And add this line to the INSTALLED_APPS section:

INSTALLED_APPS = [
    ...
    'opencensus.trace.ext.django',
]

You can configure the sampler, exporter, propagator using the OPENCENSUS_TRACE setting in settings.py:

OPENCENSUS_TRACE = {
    'SAMPLER': 'opencensus.trace.samplers.probability.ProbabilitySampler',
    'EXPORTER': 'opencensus.trace.exporters.print_exporter.PrintExporter',
    'PROPAGATOR': 'opencensus.trace.propagation.google_cloud_format.'
                  'GoogleCloudFormatPropagator',
}

You can configure the sampling rate and other parameters using the OPENCENSUS_TRACE_PARAMS setting in settings.py:

OPENCENSUS_TRACE_PARAMS = {
    'BLACKLIST_PATHS': ['/_ah/health'],
    'GCP_EXPORTER_PROJECT': None,
    'SAMPLING_RATE': 0.5,
    'ZIPKIN_EXPORTER_SERVICE_NAME': 'my_service',
    'ZIPKIN_EXPORTER_HOST_NAME': 'localhost',
    'ZIPKIN_EXPORTER_PORT': 9411,
}

Pyramid

In your application, add the pyramid tween and your requests will be traced.

def main(global_config, **settings):
    config = Configurator(settings=settings)

    config.add_tween('opencensus.trace.ext.pyramid'
                     '.pyramid_middleware.OpenCensusTweenFactory')

To configure the sampler, exporter, and propagator, pass the instances into the pyramid settings

from opencensus.trace.exporters import print_exporter
from opencensus.trace.propagation import google_cloud_format
from opencensus.trace.samplers import probability

settings = {}
settings['OPENCENSUS_TRACE'] = {
    'EXPORTER': print_exporter.PrintExporter(),
    'SAMPLER': probability.ProbabilitySampler(rate=0.5),
    'PROPAGATOR': google_cloud_format.GoogleCloudFormatPropagator(),
}

config = Configurator(settings=settings)

gRPC Integration

OpenCensus provides the implementation of interceptors for both the client side and server side to instrument the gRPC requests and responses. The client interceptors are used to create a decorated channel that intercepts client gRPC calls and server interceptors act as decorators over handlers.

gRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade your grpcio to the latest version to use this feature.

For sample usage, please refer to the hello world example in the examples directory.

More information about the gRPC interceptors please see the proposal.

Service Integration

Opencensus supports integration with various popular outbound services such as MySQL and Requests. To enable integration you will need to pass the list of services to census:

from opencensus.trace import config_integration
from opencensus.trace import tracer as tracer_module

import mysql.connector

# Trace both mysql-connection and psycopg2
integration = ['mysql', 'postgresql']

config_integration.trace_integrations(integration)

MySQL

The integration with MySQL supports the mysql-connector library and is specified to trace_integrations using 'mysql'.

PostgreSQL

The integration with PostgreSQL supports the psycopg2 library and is specified to trace_integrations using 'postgresql'.

SQLAlchemy

You can trace usage of the sqlalchemy package, regardless of the underlying database, by specifying 'sqlalchemy' to trace_integrations.

Note

If you enable tracing of SQLAlchemy as well as the underlying database driver, you will get duplicate spans. Instead, just trace SQLAlchemy.

Requests

Census can trace HTTP requests made with the Requests package. The request URL, method, and status will be collected.

You can enable Requests integration by specifying 'requests' to trace_integrations.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information on how to get started.

Development

Tests

cd trace
tox -e py34
source .tox/py34/bin/activate

# Run the unit test
pip install nox-automation

# See what's available in the nox suite
nox -l

# Run a single nox command
nox -s "unit_tests(python_version='2.7')"

# Run all the nox commands
nox

# Integration test
# We don't have script for integration test yet, but can test as below.
python setup.py bdist_wheel
cd dist
pip install opencensus-0.0.1-py2.py3-none-any.whl

# Then just run the tracers normally as you want to test.

License

Apache 2.0 - See LICENSE for more information.

Disclaimer

This is not an official Google product.

pitabwire/opencensus-python