opencensus 0.1.4

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

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',
    'REPORTER': '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)

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.