Skip to content
A stats collection and distributed tracing framework
Branch: master
Clone or download
reyang Refactor Django/Pyramid configuration (#624)
refactor Pyramid config
decouple exporter logic from Django extension
use tracecontext as the default propagator
Latest commit f0064d8 Apr 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Don't let CircleCI build the gh-pages branch (#415) Nov 29, 2018
.github
context/opencensus-context v0.4.x master version updates (#606) Apr 9, 2019
contrib Refactor Django/Pyramid configuration (#624) Apr 20, 2019
docs Refactor context propagation to work with async (#588) Apr 1, 2019
examples Stackdriver poll-based metrics (#593) Apr 2, 2019
opencensus
scripts Don't exit on twine upload failures (#607) Apr 9, 2019
tests
.coveragerc Remove vendor proto files and use opencensus-proto instead. (#596) Apr 12, 2019
.gitignore Monitored Resource: replace gke_container with k8s_container in Stack… ( Sep 22, 2018
.travis.yml Add api documentation to the doc tree (#88) Nov 29, 2017
AUTHORS Replace Google in copyright boilerplate (#530) Feb 27, 2019
CHANGELOG.md v0.4.x master version updates (#606) Apr 9, 2019
CODE_OF_CONDUCT.md Initial repository setup Jul 24, 2017
CONTRIBUTING.md Initial repository setup Jul 24, 2017
LICENSE Initial repository setup Jul 24, 2017
MANIFEST.in Initial repository setup Jul 24, 2017
Makefile Build docs using sphinx (#53) Nov 2, 2017
README.rst
RELEASING.md Remove manual version update from release steps (#372) Oct 30, 2018
nox.py Initial version of Azure extension (#613) Apr 12, 2019
requirements-test.txt clean up package specific dependencies (#557) Mar 14, 2019
setup.cfg Initial repository setup Jul 24, 2017
setup.py v0.4.x master version updates (#606) Apr 9, 2019
tox.ini [WIP] Implementation of Python Stats API (#149) May 15, 2018

README.rst

OpenCensus - A stats collection and distributed tracing framework

gitter circleci pypi

OpenCensus for Python. OpenCensus 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 OpenCensus.

Tracing

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 import tracer as tracer_module
    
    tracer = tracer_module.Tracer()
  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 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()

OpenCensus 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

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 opencensus.trace.print_exporter, opencensus.trace.file_exporter and opencensus.trace.logging_exporter, other exporters are provided as extensions.

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

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

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

Propagators

You can specify the propagator type for serializing and deserializing the SpanContext and its headers. The default propagator is TraceContextPropagator, the rest options are BinaryFormatPropagator, 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)

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 in settings.py:

OPENCENSUS: {
    'TRACE': {
        ...
        '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.

Extensions

Integration

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

Trace Exporter

Stats Exporter

Additional Info

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

# Install nox with pip
pip install nox-automation

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

# Run a single nox command
nox -s "unit(py='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.

You can’t perform that action at this time.