opencensus-python

A stats collection and distributed tracing framework

  • Owner: census-instrumentation/opencensus-python
  • Platform:
  • License:: Apache License 2.0
  • Category::
  • Topic:
  • Like:
    0
      Compare:

Github stars Tracking Chart

OpenCensus - A stats collection and distributed tracing framework
=================================================================, gitter, circleci, pypi, compat_check_pypi, compat_check_github, .., circleci, image:: https://circleci.com/gh/census-instrumentation/opencensus-python.svg?style=shield
:target: https://circleci.com/gh/census-instrumentation/opencensus-python
.., gitter, image:: https://badges.gitter.im/census-instrumentation/lobby.svg
:target: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
.., pypi, image:: https://badge.fury.io/py/opencensus.svg
:target: https://pypi.org/project/opencensus/
.., compat_check_pypi, image:: https://python-compatibility-tools.appspot.com/one_badge_image?package=opencensus
:target: https://python-compatibility-tools.appspot.com/one_badge_target?package=opencensus
.., compat_check_github, image:: https://python-compatibility-tools.appspot.com/one_badge_image?package=git%2Bgit%3A//github.com/census-instrumentation/opencensus-python.git
:target: https://python-compatibility-tools.appspot.com/one_badge_target?package=git%2Bgit%3A//github.com/census-instrumentation/opencensus-python.git

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.

.. _OpenCensus: https://github.com/census-instrumentation

  • API Documentation_

.. _API Documentation: https://opencensus.io/api/python/trace/usage.html


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:

    .. code:: python

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

    .. _pip: https://pip.pypa.io
    .. _pipenv: https://docs.pipenv.org/

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

    .. code:: python

     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_:

.. code:: python

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:

.. code:: python

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

.. _context manager: https://docs.python.org/3/reference/datamodel.html#context-managers

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 <#trace-exporter>__.

  • 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.

.. code:: python

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 <#integration>_.

.. code:: python

'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.

  • Django_
  • Flask_
  • gevent_
  • Google Cloud Client Libraries_
  • gRPC_
  • httplib_
  • logging_
  • MySQL_
  • PostgreSQL_
  • pymongo_
  • PyMySQL_
  • Pyramid_
  • requests_
  • SQLAlchemy_
  • threading_

Log Exporter

  • Azure_

Metrics Exporter

  • Azure_

Stats Exporter

  • OCAgent_
  • Prometheus_
  • Stackdriver_

Trace Exporter

  • Azure_
  • Datadog_
  • Jaeger_
  • OCAgent_
  • Stackdriver_
  • Zipkin_

.. _Azure: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-azure
.. _Datadog: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-datadog
.. _Django: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-django
.. _Flask: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-flask
.. _gevent: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-gevent
.. _Google Cloud Client Libraries: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-google-cloud-clientlibs
.. _gRPC: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-grpc
.. _httplib: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-httplib
.. _Jaeger: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-jaeger
.. _logging: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-logging
.. _MySQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-mysql
.. _OCAgent: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-ocagent
.. _PostgreSQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-postgresql
.. _Prometheus: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-prometheus
.. _pymongo: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pymongo
.. _PyMySQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pymysql
.. _Pyramid: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pyramid
.. _requests: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-requests
.. _SQLAlchemy: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-sqlalchemy
.. _Stackdriver: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-stackdriver
.. _threading: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-threading
.. _Zipkin: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-zipkin


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.

.. _Semantic Versioning: https://semver.org/

Main metrics

Overview
Name With Ownercensus-instrumentation/opencensus-python
Primary LanguagePython
Program languagePython (Language Count: 4)
Platform
License:Apache License 2.0
所有者活动
Created At2017-07-07 22:28:28
Pushed At2025-06-12 19:13:16
Last Commit At2025-06-12 15:13:16
Release Count45
Last Release Nameopencensus-ext-azure@1.1.15 (Posted on )
First Release Name0.1.2 (Posted on )
用户参与
Stargazers Count673
Watchers Count37
Fork Count251
Commits Count575
Has Issues Enabled
Issues Count482
Issue Open Count173
Pull Requests Count618
Pull Requests Open Count45
Pull Requests Close Count107
项目设置
Has Wiki Enabled
Is Archived
Is Fork
Is Locked
Is Mirror
Is Private