diff --git a/README.rst b/README.rst index 92f61ca6e..f73251fa5 100644 --- a/README.rst +++ b/README.rst @@ -103,114 +103,71 @@ Alternatively, you can explicitly start and end a span: Customization ------------- -Samplers -~~~~~~~~ +There are several things you can customize in OpenCensus: -You can specify different samplers when initializing a tracer, default -is using ``AlwaysOnSampler``, the other options are ``AlwaysOffSampler`` -and ``ProbabilitySampler`` +* **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. -.. code:: python - - 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) - -Exporters -~~~~~~~~~ - -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 <#trace-exporter>`__. - -This example shows how to configure OpenCensus to save the traces to a -file: - -.. code:: python - - from opencensus.trace import file_exporter - from opencensus.trace.tracers import context_tracer +* **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>`__. - exporter = file_exporter.FileExporter(file_name='traces') - tracer = context_tracer.ContextTracer(exporter=exporter) +* **Sampler**, which determines how traces are sampled. + The default sampler is ``AlwaysOnSampler``, other samplers include the + ``AlwaysOffSampler`` and ``ProbabilitySampler``. -Propagators -~~~~~~~~~~~ +* **Propagator**, which serializes and deserializes the + ``SpanContext`` and its headers. The default propagator is + ``TraceContextPropagator``, other propagators include + ``BinaryFormatPropagator``, ``GoogleCloudFormatPropagator`` and + ``TextFormatPropagator``. -You can specify the propagator type for serializing and deserializing the -``SpanContext`` and its headers. The default propagator is -``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, -``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``. -This example shows how to use the ``GoogleCloudFormatPropagator``: - -.. code:: python - - 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``: +You can customize while initializing a tracer. .. code:: python 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 + 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(propagator=TraceContextPropagator()) + + 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') -Blacklist Paths -~~~~~~~~~~~~~~~ - -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: +You can use a configuration file for Flask/Django/Pyramid. For more +information, please read the +`individual integration documentation <#integration>`_. .. code:: python - 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`` in ``settings.py``: - -.. code:: python - - OPENCENSUS: { + 'OPENCENSUS': { 'TRACE': { - ... - 'BLACKLIST_PATHS': ['_ah/health',], + '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()', } } - -.. 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. - ------------ Extensions ------------ diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index a58c7e43f..ac17e6553 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -5,3 +5,74 @@ OpenCensus Runtime Context .. |pypi| image:: https://badge.fury.io/py/opencensus-context.svg :target: https://pypi.org/project/opencensus-context/ + +The **OpenCensus Runtime Context** provides in-process context propagation. +By default, ``thread local storage`` is used for Python 2.7, 3.4 and 3.5; +``contextvars`` is used for Python >= 3.6, which provides ``asyncio`` support. + +Installation +------------ + +This library is installed by default with ``opencensus``, there is no need +to install it explicitly. + +Usage +----- + +In most cases context propagation happens automatically within a process, +following the control flow of threads and asynchronous coroutines. The runtime +context is a dictionary stored in a `context variable `_ +when available, and in `thread local storage `_ +otherwise. + +There are cases where you may want to propagate the context explicitly: + +Explicit Thread Creation +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: python + + from threading import Thread + from opencensus.common.runtime_context import RuntimeContext + + def work(name): + # here you will get the context from the parent thread + print(RuntimeContext) + + thread = Thread( + # propagate context explicitly + target=RuntimeContext.with_current_context(work), + args=('foobar',), + ) + thread.start() + thread.join() + +Thread Pool +~~~~~~~~~~~ + +.. code:: python + + from multiprocessing.dummy import Pool as ThreadPool + from opencensus.common.runtime_context import RuntimeContext + + def work(name): + # here you will get the context from the parent thread + print(RuntimeContext) + + pool = ThreadPool(2) + # propagate context explicitly + pool.map(RuntimeContext.with_current_context(work), [ + 'bear', + 'cat', + 'dog', + 'horse', + 'rabbit', + ]) + pool.close() + pool.join() + +References +---------- + +* `Examples `_ +* `OpenCensus Project `_