opencensus 0.1.11

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)

StackdriverExporter requires the google-cloud-trace package. Install google-cloud-trace using pip or pipenv:

pip install google-cloud-trace
pipenv install google-cloud-trace

By default, traces are exported synchronously, which introduces latency during your code’s execution. To avoid blocking code execution, you can initialize your exporter to use a background thread.

This example shows how to configure Census to use a background thread:

from opencensus.trace.exporters import stackdriver_exporter
from opencensus.trace import tracer as tracer_module
from opencensus.trace.exporters.transports.background_thread \
    import BackgroundThreadTransport

exporter = stackdriver_exporter.StackdriverExporter(
    project_id='your_cloud_project', transport=BackgroundThreadTransport)
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 three built in propagators: GoogleCloudFormatPropagator, TextFormatPropagator and TraceContextPropagator.

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)

This example shows how to use the TraceContextPropagator:

import requests

from opencensus.trace import config_integration
from opencensus.trace.propagation.trace_context_http_header_format import TraceContextPropagator
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(['httplib'])
tracer = Tracer(propagator = TraceContextPropagator())

with tracer.span(name = 'parent'):
    with tracer.span(name = 'child'):
        response = requests.get('http://localhost:5000')

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',],
}

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,
    'SERVICE_NAME': 'my_service',
    'ZIPKIN_EXPORTER_HOST_NAME': 'localhost',
    'ZIPKIN_EXPORTER_PORT': 9411,
    'ZIPKIN_EXPORTER_PROTOCOL': 'http',
}

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)

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.

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.

Google Cloud Client Libraries

Census can trace HTTP and gRPC requests made with the Cloud client libraries. The request URL, method, and status will be collected.

You can enable Google Cloud client libraries integration by specifying 'google_cloud_clientlibs' to trace_integrations.

Stackdriver Exporter Usage

Prometheus Exporter Usage