Package: criteo-fork-opencensus
Censusfor Python. Census 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 Census.API DocumentationTracingInstallation & basic usageInstall the opencensus package usingpiporpipenv:pip install opencensus
pipenv install opencensusInitialize a tracer for your application:fromopencensus.traceimporttracerastracer_moduletracer=tracer_module.Tracer()Initialize a view_manager and a stats_recorder for your application:fromopencensus.statsimportstatsasstats_modulestats=stats_module.Stats()view_manager=stats.view_managerstats_recorder=stats.stats_recorderUsageYou can collect traces using theTracercontext manager:fromopencensus.traceimporttracerastracer_module# Initialize a tracer, by default using the `PrintExporter`tracer=tracer_module.Tracer()# Example for creating nested spanswithtracer.span(name='span1')asspan1:do_something_to_trace()withspan1.span(name='span1_child1')asspan1_child1:do_something_to_trace()withspan1.span(name='span1_child2')asspan1_child2:do_something_to_trace()withtracer.span(name='span2')asspan2:do_something_to_trace()Census will collect everything within thewithstatement as a single span.Alternatively, you can explicitly start and end a span:fromopencensus.traceimporttracerastracer_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()CustomizationSamplersYou can specify different samplers when initializing a tracer, default
is usingAlwaysOnSampler, the other options areAlwaysOffSamplerandProbabilitySamplerfromopencensus.trace.samplersimportprobabilityfromopencensus.traceimporttracerastracer_module# Sampling the requests at the rate equals 0.5sampler=probability.ProbabilitySampler(rate=0.5)tracer=tracer_module.Tracer(sampler=sampler)ExportersYou can choose different exporters to send the traces to. By default,
the traces are printed to stdout in JSON format. Other options include
writing to a file, sending to Python logging, or reporting to
Stackdriver.This example shows how to configure Census to save the traces to a
file:fromopencensus.trace.exportersimportfile_exporterfromopencensus.trace.tracersimportcontext_tracerexporter=file_exporter.FileExporter(file_name='traces')tracer=context_tracer.ContextTracer(exporter=exporter)This example shows how to report the traces to Stackdriver Trace:fromopencensus.trace.exportersimportstackdriver_exporterfromopencensus.traceimporttracerastracer_moduleexporter=stackdriver_exporter.StackdriverExporter(project_id='your_cloud_project')tracer=tracer_module.Tracer(exporter=exporter)StackdriverExporter requires the google-cloud-trace package. Install
google-cloud-trace usingpiporpipenv:pip install google-cloud-trace
pipenv install google-cloud-traceBy default, traces are exported synchronously, which introduces latency during
your code’s execution. To avoid blocking code execution, you can initialize
your exporter to use a background thread.This example shows how to configure Census to use a background thread:fromopencensus.trace.exportersimportstackdriver_exporterfromopencensus.traceimporttracerastracer_modulefromopencensus.trace.exporters.transports.background_thread\importBackgroundThreadTransportexporter=stackdriver_exporter.StackdriverExporter(project_id='your_cloud_project',transport=BackgroundThreadTransport)tracer=tracer_module.Tracer(exporter=exporter)PropagatorsYou can specify the propagator type for serializing and deserializing theSpanContextand its headers. There are currently three built in propagators:GoogleCloudFormatPropagator,TextFormatPropagatorandTraceContextPropagator.This example shows how to use theGoogleCloudFormatPropagator:fromopencensus.trace.propagationimportgoogle_cloud_formatpropagator=google_cloud_format.GoogleCloudFormatPropagator()# Deserializespan_context=propagator.from_header(header)# Serializeheader=propagator.to_header(span_context)This example shows how to use theTraceContextPropagator:importrequestsfromopencensus.traceimportconfig_integrationfromopencensus.trace.propagation.trace_context_http_header_formatimportTraceContextPropagatorfromopencensus.trace.tracerimportTracerconfig_integration.trace_integrations(['httplib'])tracer=Tracer(propagator=TraceContextPropagator())withtracer.span(name='parent'):withtracer.span(name='child'):response=requests.get('http://localhost:5000')Blacklist PathsYou 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/healthendpoint
for a Flask application:fromopencensus.trace.ext.flask.flask_middlewareimportFlaskMiddlewareapp=flask.Flask(__name__)blacklist_paths=['_ah/health']middleware=FlaskMiddleware(app,blacklist_paths=blacklist_paths)For Django, you can configure the blacklist in theOPENCENSUS_PARAMSinsettings.py:OPENCENSUS_PARAMS:{...'BLACKLIST_PATHS':['_ah/health',],}NoteBy 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.Framework IntegrationCensus supports integration with popular web frameworks including
Django, Flask, Pyramid, and Webapp2. When the application receives a HTTP request,
the tracer will automatically generate a span context using the trace
information extracted from the request headers and propagated to the
child spans.FlaskIn your application, use the middleware to wrap your app and the
requests will be automatically traced.fromopencensus.trace.ext.flask.flask_middlewareimportFlaskMiddlewareapp=flask.Flask(__name__)# You can also specify the sampler, exporter, propagator in the middleware,# default is using `AlwaysOnSampler` as sampler, `PrintExporter` as exporter,# `GoogleCloudFormatPropagator` as propagator.middleware=FlaskMiddleware(app)DjangoFor tracing Django requests, you will need to add the following line to
theMIDDLEWARE_CLASSESsection in the Djangosettings.pyfile.MIDDLEWARE_CLASSES=[...'opencensus.trace.ext.django.middleware.OpencensusMiddleware',]And add this line to theINSTALLED_APPSsection:INSTALLED_APPS=[...'opencensus.trace.ext.django',]You can configure the sampler, exporter, propagator using theOPENCENSUS_TRACEsetting insettings.py:OPENCENSUS_TRACE={'SAMPLER':'opencensus.trace.samplers.probability.ProbabilitySampler','EXPORTER':'opencensus.trace.exporters.print_exporter.PrintExporter','PROPAGATOR':'opencensus.trace.propagation.google_cloud_format.''GoogleCloudFormatPropagator',}You can configure the sampling rate and other parameters using theOPENCENSUS_TRACE_PARAMSsetting insettings.py:OPENCENSUS_TRACE_PARAMS={'BLACKLIST_PATHS':['/_ah/health'],'GCP_EXPORTER_PROJECT':None,'SAMPLING_RATE':0.5,'SERVICE_NAME':'my_service','ZIPKIN_EXPORTER_HOST_NAME':'localhost','ZIPKIN_EXPORTER_PORT':9411,'ZIPKIN_EXPORTER_PROTOCOL':'http',}PyramidIn your application, add the pyramid tween and your requests will be
traced.defmain(global_config,**settings):config=Configurator(settings=settings)config.add_tween('opencensus.trace.ext.pyramid''.pyramid_middleware.OpenCensusTweenFactory')To configure the sampler, exporter, and propagator, pass the instances
into the pyramid settingsfromopencensus.trace.exportersimportprint_exporterfromopencensus.trace.propagationimportgoogle_cloud_formatfromopencensus.trace.samplersimportprobabilitysettings={}settings['OPENCENSUS_TRACE']={'EXPORTER':print_exporter.PrintExporter(),'SAMPLER':probability.ProbabilitySampler(rate=0.5),'PROPAGATOR':google_cloud_format.GoogleCloudFormatPropagator(),}config=Configurator(settings=settings)gRPC IntegrationOpenCensus provides the implementation of interceptors for both the client side
and server side to instrument the gRPC requests and responses. The client
interceptors are used to create a decorated channel that intercepts client
gRPC calls and server interceptors act as decorators over handlers.gRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade
your grpcio to the latest version to use this feature.For sample usage, please refer to the hello world example in the examples
directory.More information about the gRPC interceptors please see theproposal.Service IntegrationOpencensus supports integration with various popular outbound services such as
SQL packages, Requests and Google Cloud client libraries. To enable integration
services to census:     you will need to pass the list of services to census:fromopencensus.traceimportconfig_integrationfromopencensus.traceimporttracerastracer_moduleimportmysql.connector# Trace both mysql-connection and psycopg2integration=['mysql','postgresql']config_integration.trace_integrations(integration)MySQLThe integration with MySQL supports themysql-connectorlibrary and is specified
totrace_integrationsusing'mysql'.PostgreSQLThe integration with PostgreSQL supports thepsycopg2library and is specified
totrace_integrationsusing'postgresql'.SQLAlchemyYou can trace usage of thesqlalchemy package, regardless of the underlying
database, by specifying'sqlalchemy'totrace_integrations.NoteIf you enable tracing of SQLAlchemy as well as the underlying database
driver, you will get duplicate spans. Instead, just trace SQLAlchemy.RequestsCensus can trace HTTP requests made with theRequests package. The request URL,
method, and status will be collected.You can enable Requests integration by specifying'requests'totrace_integrations.Google Cloud Client LibrariesCensus can trace HTTP and gRPC requests made with theCloud client libraries.
The request URL, method, and status will be collected.You can enable Google Cloud client libraries integration by specifying'google_cloud_clientlibs'totrace_integrations.ThreadingCensus can propagate trace across threads when using the Threading package.You can enable Threading integration by specifying'threading'totrace_integrations.StatsStackdriver StatsThe OpenCensus Stackdriver Stats Exporter allows users
to export metrics to Stackdriver Monitoring.
The API of this project is still evolving.
The use of vendoring or a dependency management tool is recommended.Stackdriver Exporter UsageStackdriver Importfromopencensus.stats.exportersimportstackdriver_exporterasstackdriverfromopencensus.statsimportstatsasstats_moduleStackdriver PrerequisitesOpenCensus Python libraries require Python 2.7 or later.Google Cloud Platform account and project.Google Stackdriver Monitoring enabled on your project (Need help?Click here).Register the Stackdriver exporterstats=stats_module.Stats()view_manager=stats.view_managerexporter=stackdriver.new_stats_exporter(stackdriver.Options(project_id="<id_value>"))view_manager.register_exporter(exporter)...Stackdriver Code ReferenceIn theexamplesfolder, you can find all the necessary steps to get the exporter, register a view, put tags on the measure, and see the values against the Stackdriver monitoring tool once you have defined theproject_id.For further details for the Stackdriver implementation, see the filestackdriver_exporter.py.Path & FileShort Descriptionexamples/stats/exporter/stackdriver.pyEnd to end exampleopencensus/stats/exporters/stackdriver_exporter.pyStats implementation for StackdriverPrometheus StatsThe OpenCensusPrometheusStats Exporter allows users
to export metrics to Prometheus monitoring solution.
The API of this project is still evolving.
The use of vendoring or a dependency management tool is recommended.Prometheus Exporter UsagePrometheus Importfromopencensus.stats.exportersimportprometheus_exporterasprometheusfromopencensus.statsimportstatsasstats_modulePrometheus PrerequisitesOpenCensus Python libraries require Python 2.7 or later.Prometheus up and running.Register the Prometheus exporterstats=stats_module.Stats()view_manager=stats.view_managerexporter=prometheus.new_stats_exporter(prometheus.Options(namespace="<namespace>"))view_manager.register_exporter(exporter)...Prometheus Code ReferenceIn theexamplesfolder, you can find all the necessary steps to get the exporter, register a view, put tags on the measure, and see the values against the Prometheus monitoring tool.For further details for the Prometheus implementation, see the fileprometheus_exporter.py.Path & FileShort Descriptionexamples/stats/exporter/prometheus.pyEnd to end exampleopencensus/stats/exporters/prometheus_exporter.pyStats implementation for PrometheusAdditional InfoContributingContributions to this library are always welcome and highly encouraged.SeeCONTRIBUTINGfor more information on how to
get started.DevelopmentTestscd 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.LicenseApache 2.0 - SeeLICENSEfor more information.DisclaimerThis is not an official Google product.