opencensus 0.3.0

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 OpenCensus 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.ext.stackdriver import trace_exporter as 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 OpenCensus to use a background thread:

from opencensus.common.transports.async_ import AsyncTransport
from opencensus.ext.stackdriver import trace_exporter as stackdriver_exporter
from opencensus.trace import tracer as tracer_module

exporter = stackdriver_exporter.StackdriverExporter(
    project_id='your_cloud_project', transport=AsyncTransport)
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_TRACE_PARAMS in settings.py:

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

Stackdriver Exporter Usage

Prometheus Exporter Usage