Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

A stats collection and distributed tracing framework

Project description

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

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 AlwaysOnSampler, other samplers include the AlwaysOffSampler and ProbabilitySampler.
  • 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 probability

config_integration.trace_integrations(['httplib'])

tracer = tracer_module.Tracer(
    exporter=file_exporter.FileExporter(file_name='traces'),
    propagator=google_cloud_format.GoogleCloudFormatPropagator(),
    sampler=probability.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()',
    }
}

Extensions

Integration

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

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
opencensus-0.5.0-py2.py3-none-any.whl (125.4 kB) Copy SHA256 hash SHA256 Wheel py2.py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page