Docs

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

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 <https://docs.python.org/3/library/contextvars.html>`_
+when available, and in `thread local storage <https://docs.python.org/2/library/threading.html#threading.local>`_
+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 <https://github.com/census-instrumentation/opencensus-python/tree/master/context/opencensus-context/examples>`_
+* `OpenCensus Project <https://opencensus.io/>`_