Skip to main content

A stats collection and distributed tracing framework

Project description

gitter travisci circleci pypi compat_check_pypi compat_check_github

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.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'):
    do_something_to_trace()
    with tracer.span(name='span1_child1'):
        do_something_to_trace()
    with tracer.span(name='span1_child2'):
        do_something_to_trace()
with tracer.span(name='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:

  • Excludelist, 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 excludelist 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': {
        'EXCLUDELIST_HOSTNAMES': ['localhost', '127.0.0.1'],
        'EXCLUDELIST_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.

Log Exporter

Metrics Exporter

Stats Exporter

Trace Exporter

Versioning

This library follows Semantic Versioning.

GA: Libraries defined at a GA quality level are stable, and will not introduce backwards-incompatible changes in any minor or patch releases. We will address issues and requests with the highest priority. If we were to make a backwards-incompatible changes on an API, we will first mark the existing API as deprecated and keep it for 18 months before removing it.

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we’re working towards their release candidate. We will address issues and requests with a higher priority. There may be backwards incompatible changes in a minor version release, though not in a patch release. If an element is part of an API that is only meant to be used by exporters or other opencensus libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18 months before removing it, if possible.

Project details


Download files

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

Source Distribution

opencensus-0.11.4.tar.gz (65.0 kB view details)

Uploaded Source

Built Distribution

opencensus-0.11.4-py2.py3-none-any.whl (128.2 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file opencensus-0.11.4.tar.gz.

File metadata

  • Download URL: opencensus-0.11.4.tar.gz
  • Upload date:
  • Size: 65.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.7.9

File hashes

Hashes for opencensus-0.11.4.tar.gz
Algorithm Hash digest
SHA256 cbef87d8b8773064ab60e5c2a1ced58bbaa38a6d052c41aec224958ce544eff2
MD5 9e8d189fc0af24656b1451b1c1c34862
BLAKE2b-256 15a7a46dcffa1b63084f9f17fe3c8cb20724c4c8f91009fd0b2cfdb27d5d2b35

See more details on using hashes here.

File details

Details for the file opencensus-0.11.4-py2.py3-none-any.whl.

File metadata

  • Download URL: opencensus-0.11.4-py2.py3-none-any.whl
  • Upload date:
  • Size: 128.2 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.7.9

File hashes

Hashes for opencensus-0.11.4-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 a18487ce68bc19900336e0ff4655c5a116daf10c1b3685ece8d971bddad6a864
MD5 6c7843942ab39cda33c20605c687e7b3
BLAKE2b-256 b5ed9fbdeb23a09e430d87b7d72d430484b88184633dc50f6bfb792354b6f661

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page