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.
Install the opencensus package using pip or pipenv:
pip install opencensus pipenv install opencensus
Initialize a tracer for your application:
from opencensus.trace import tracer as tracer_module tracer = tracer_module.Tracer()
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
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()
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)
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)
You can specify the propagator type for serializing and deserializing the
SpanContext
and its headers. There are currently three built in propagators:
GoogleCloudFormatPropagator
, TextFormatPropagator
and TraceContextPropagator
.
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')
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_TRACE_PARAMS
in settings.py
:
OPENCENSUS_TRACE_PARAMS: {
...
'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.
OpenCensus supports integration with popular web frameworks, client libraries and built-in libraries.
- Django
- Flask
- Google Cloud Client Libraries
- gRPC
- httplib
- MySQL
- PostgreSQL
- pymongo
- PyMySQL
- Pyramid
- requests
- SQLAlchemy
- threading
Contributions to this library are always welcome and highly encouraged.
See CONTRIBUTING for more information on how to get started.
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.
Apache 2.0 - See LICENSE for more information.
This is not an official Google product.