opencensus 0.6.0

Installation & basic usage

1. Install the opencensus package using pip or pipenv:

   pip install opencensus
   pipenv install opencensus

2. Initialize a tracer for your application:

   from opencensus.trace.tracer import Tracer
   from opencensus.trace.samplers import AlwaysOnSampler
   
   tracer = Tracer(sampler=AlwaysOnSampler())

3. Initialize a view_manager and a stats_recorder for your application:

   from opencensus.stats import stats as stats_module
   
   stats = stats_module.stats
   view_manager = stats.view_manager
   stats_recorder = stats.stats_recorder

Usage

You can collect traces using the Tracer context manager:

from opencensus.trace.tracer import Tracer
from opencensus.trace.samplers import AlwaysOnSampler

# Initialize a tracer, by default using the `PrintExporter`
tracer = Tracer(sampler=AlwaysOnSampler())

# 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()

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

Alternatively, you can explicitly start and end a span:

from opencensus.trace.tracer import Tracer
from opencensus.trace.samplers import AlwaysOnSampler

# Initialize a tracer, by default using the `PrintExporter`
tracer = Tracer(sampler=AlwaysOnSampler())

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

Customization

There are several things you can customize in OpenCensus:

• Blacklist, which excludes certain hosts and paths from being tracked. By default, the health check path for the App Engine flexible environment is not tracked, you can turn it on by excluding it from the blacklist setting.

• Exporter, which sends the traces. By default, the traces are printed to stdout in JSON format. You can choose different exporters to send the traces to. There are three built-in exporters, which are PrintExporter, FileExporter and LoggingExporter, the other exporters are provided as extensions.

• Sampler, which determines how traces are sampled. The default sampler is the ProbabilitySampler, which samples (i.e. enables tracing for) a percentage of all requests. Sampling is deterministic according to the trace ID. To force sampling for all requests, or to prevent any request from being sampled, see AlwaysOnSampler and AlwaysOffSampler.

• Propagator, which serializes and deserializes the SpanContext and its headers. The default propagator is TraceContextPropagator, other propagators include BinaryFormatPropagator, GoogleCloudFormatPropagator and TextFormatPropagator.

You can customize while initializing a tracer.

import requests

from opencensus.trace import config_integration
from opencensus.trace import file_exporter
from opencensus.trace import tracer as tracer_module
from opencensus.trace.propagation import google_cloud_format
from opencensus.trace.samplers import ProbabilitySampler

config_integration.trace_integrations(['httplib'])

tracer = tracer_module.Tracer(
    exporter=file_exporter.FileExporter(file_name='traces'),
    propagator=google_cloud_format.GoogleCloudFormatPropagator(),
    sampler=ProbabilitySampler(rate=0.5),
)

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

You can use a configuration file for Flask/Django/Pyramid. For more information, please read the individual integration documentation.

'OPENCENSUS': {
    'TRACE': {
        'BLACKLIST_HOSTNAMES': ['localhost', '127.0.0.1'],
        'BLACKLIST_PATHS': ['_ah/health'],
        'SAMPLER': 'opencensus.trace.samplers.ProbabilitySampler(rate=1)',
        'EXPORTER': '''opencensus.ext.ocagent.trace_exporter.TraceExporter(
            service_name='foobar',
        )''',
        'PROPAGATOR': 'opencensus.trace.propagation.google_cloud_format.GoogleCloudFormatPropagator()',
    }
}

Integration

OpenCensus supports integration with popular web frameworks, client libraries and built-in libraries.

• Django

• Flask

• gevent

• Google Cloud Client Libraries

• gRPC

• httplib

• logging

• MySQL

• PostgreSQL

• pymongo

• PyMySQL

• Pyramid

• requests

• SQLAlchemy

• threading

Trace Exporter

• Azure

• Jaeger

• OCAgent

• Stackdriver

• Zipkin

Stats Exporter

• OCAgent

• Prometheus

• Stackdriver

Log Exporter

• Azure