From fdf9fbb4ea88d475747f0da7fd33313682029ef3 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 14:36:48 -0700 Subject: [PATCH 01/17] update README for opencensus-context lib --- context/opencensus-context/README.rst | 68 +++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index a58c7e43f..0033b7f54 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -5,3 +5,71 @@ OpenCensus Runtime Context .. |pypi| image:: https://badge.fury.io/py/opencensus-context.svg :target: https://pypi.org/project/opencensus-context/ + +Installation +------------ + +This library comes by default when you install OpenCensus, there is no need +to install it explicitly. + +:: + + pip install opencensus-context + +Usage +----- + +The OpenCensus Runtime Context provides the 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. + +By default, context would flow in the same thread and async task. 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 `_ From c7a333a201add4389555f5ea5cfe02b391bf9981 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 14:39:02 -0700 Subject: [PATCH 02/17] update doc --- context/opencensus-context/README.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index 0033b7f54..f84c1b97d 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -12,14 +12,10 @@ Installation This library comes by default when you install OpenCensus, there is no need to install it explicitly. -:: - - pip install opencensus-context - Usage ----- -The OpenCensus Runtime Context provides the in-process context propagation. +The **OpenCensus Runtime Context** provides the 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. From 61c296f81917134796c0ae3b629b4dab7370f63b Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 14:40:31 -0700 Subject: [PATCH 03/17] update doc --- context/opencensus-context/README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index f84c1b97d..a802a7512 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -6,6 +6,10 @@ 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 the 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 ------------ @@ -15,10 +19,6 @@ to install it explicitly. Usage ----- -The **OpenCensus Runtime Context** provides the 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. - By default, context would flow in the same thread and async task. There are cases where you may want to propagate the context explicitly: From 4ad8d54f34605130bfae20f7d7162d1318e3dc12 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:03:40 -0700 Subject: [PATCH 04/17] polish README --- README.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 92f61ca6e..d2447a890 100644 --- a/README.rst +++ b/README.rst @@ -103,12 +103,26 @@ Alternatively, you can explicitly start and end a span: Customization ------------- +There are several things you can customize how OpenCensus works: +* Blacklist, which excludes certain hosts and paths from being tracked. +* Exporter, which sends the telemetry data. + 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>`__. +* Sampler, which determines how telemetry data got sampled. + By default is using ``AlwaysOnSampler``, the other options are + ``AlwaysOffSampler`` and ``ProbabilitySampler`` +* Propagator, which is in charge of serializing and deserializing the + ``SpanContext`` and its headers. The default propagator is + ``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, + ``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``. + Samplers ~~~~~~~~ -You can specify different samplers when initializing a tracer, default -is using ``AlwaysOnSampler``, the other options are ``AlwaysOffSampler`` -and ``ProbabilitySampler`` +You can specify different samplers when initializing a tracer, .. code:: python @@ -122,11 +136,7 @@ and ``ProbabilitySampler`` 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: @@ -142,10 +152,7 @@ file: Propagators ~~~~~~~~~~~ -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``: From c915aa38d3c473d5e7cf8f0f14514beebf96646b Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:04:26 -0700 Subject: [PATCH 05/17] update doc --- README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.rst b/README.rst index d2447a890..c31203a39 100644 --- a/README.rst +++ b/README.rst @@ -104,16 +104,20 @@ Customization ------------- There are several things you can customize how OpenCensus works: + * Blacklist, which excludes certain hosts and paths from being tracked. + * Exporter, which sends the telemetry data. 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>`__. + * Sampler, which determines how telemetry data got sampled. By default is using ``AlwaysOnSampler``, the other options are ``AlwaysOffSampler`` and ``ProbabilitySampler`` + * Propagator, which is in charge of serializing and deserializing the ``SpanContext`` and its headers. The default propagator is ``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, From e82055b3e6ea081ebb1ec6f2f05fabfa459ab398 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:05:14 -0700 Subject: [PATCH 06/17] update doc --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index c31203a39..466ef743d 100644 --- a/README.rst +++ b/README.rst @@ -105,20 +105,20 @@ Customization There are several things you can customize how OpenCensus works: -* Blacklist, which excludes certain hosts and paths from being tracked. +* **Blacklist**, which excludes certain hosts and paths from being tracked. -* Exporter, which sends the telemetry data. +* **Exporter**, which sends the telemetry data. 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>`__. -* Sampler, which determines how telemetry data got sampled. +* **Sampler**, which determines how telemetry data got sampled. By default is using ``AlwaysOnSampler``, the other options are ``AlwaysOffSampler`` and ``ProbabilitySampler`` -* Propagator, which is in charge of serializing and deserializing the +* **Propagator**, which is in charge of serializing and deserializing the ``SpanContext`` and its headers. The default propagator is ``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, ``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``. From b6d4fd7b82a876e9df050d8ab4c8e2717caac4f7 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:18:27 -0700 Subject: [PATCH 07/17] update doc --- README.rst | 99 +++++++++++++----------------------------------------- 1 file changed, 23 insertions(+), 76 deletions(-) diff --git a/README.rst b/README.rst index 466ef743d..988bdab28 100644 --- a/README.rst +++ b/README.rst @@ -106,6 +106,8 @@ Customization There are several things you can customize how OpenCensus works: * **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 telemetry data. By default, the traces are printed to stdout in JSON format. You can choose @@ -123,104 +125,49 @@ There are several things you can customize how OpenCensus works: ``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, ``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``. -Samplers -~~~~~~~~ -You can specify different samplers when initializing a tracer, - -.. 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 -~~~~~~~~~ - - - -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 = file_exporter.FileExporter(file_name='traces') - tracer = context_tracer.ContextTracer(exporter=exporter) - -Propagators -~~~~~~~~~~~ - - - -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: - -.. 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``: +You can use configuration file for Flask/Django/Pyramid: .. 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. +.. note:: ------------ Extensions From 75762bd4002edc699277f1abc9e9f02ab5c6261f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:18:59 -0700 Subject: [PATCH 08/17] update doc --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 988bdab28..7e424a6ae 100644 --- a/README.rst +++ b/README.rst @@ -154,7 +154,7 @@ You can use configuration file for Flask/Django/Pyramid: .. code:: python - `OPENCENSUS`: { + 'OPENCENSUS': { 'TRACE': { 'BLACKLIST_HOSTNAMES': ['localhost', '127.0.0.1'], 'BLACKLIST_PATHS': ['_ah/health'], From 2a4dd74eab1c86706213b5187449bacf4e3ea7fc Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:22:10 -0700 Subject: [PATCH 09/17] update doc --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 7e424a6ae..1ed0d7ef4 100644 --- a/README.rst +++ b/README.rst @@ -150,7 +150,8 @@ You can customize while initializing a tracer. with tracer.span(name='child'): response = requests.get('http://localhost:5000') -You can use configuration file for Flask/Django/Pyramid: +You can use configuration file for Flask/Django/Pyramid. For more information, +please read the individual integration documentation `here <#integration>`_. .. code:: python From e07b1037d5e1d63802d28ad3bec90cf58affa233 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:25:08 -0700 Subject: [PATCH 10/17] update doc --- README.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 1ed0d7ef4..fdfef1005 100644 --- a/README.rst +++ b/README.rst @@ -112,9 +112,8 @@ There are several things you can customize how OpenCensus works: * **Exporter**, which sends the telemetry data. 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>`__. + which are ``PrintExporter``, ``FileExporter`` and ``LoggingExporter``, other + exporters are provided as `extensions <#trace-exporter>`__. * **Sampler**, which determines how telemetry data got sampled. By default is using ``AlwaysOnSampler``, the other options are From 66ffa76f7023df968a283cf8f91d53857d8f6b4a Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 15:25:56 -0700 Subject: [PATCH 11/17] update doc --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index fdfef1005..c9d824eda 100644 --- a/README.rst +++ b/README.rst @@ -112,8 +112,8 @@ There are several things you can customize how OpenCensus works: * **Exporter**, which sends the telemetry data. 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``, other - exporters are provided as `extensions <#trace-exporter>`__. + which are ``PrintExporter``, ``FileExporter`` and ``LoggingExporter``, the + other exporters are provided as `extensions <#trace-exporter>`__. * **Sampler**, which determines how telemetry data got sampled. By default is using ``AlwaysOnSampler``, the other options are From c701d70c8fe87a39e9a9149df5b0afeff768cee0 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 16:04:51 -0700 Subject: [PATCH 12/17] update doc --- README.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.rst b/README.rst index c9d824eda..f457ca6d3 100644 --- a/README.rst +++ b/README.rst @@ -166,9 +166,6 @@ please read the individual integration documentation `here <#integration>`_. } } - -.. note:: - ------------ Extensions ------------ From e57024c39a84806eb31ebffca74fc89cec7997d1 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 16:49:10 -0700 Subject: [PATCH 13/17] update doc --- README.rst | 17 +++++++++-------- context/opencensus-context/README.rst | 4 ++-- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index f457ca6d3..78c55c268 100644 --- a/README.rst +++ b/README.rst @@ -103,23 +103,23 @@ Alternatively, you can explicitly start and end a span: Customization ------------- -There are several things you can customize how OpenCensus works: +There are several ways you can customize how OpenCensus works: * **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 telemetry data. +* **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 telemetry data got sampled. - By default is using ``AlwaysOnSampler``, the other options are - ``AlwaysOffSampler`` and ``ProbabilitySampler`` +* **Sampler**, which determines how traces are sampled. + The default sampler is ``AlwaysOnSampler``, other samplers include the + ``AlwaysOffSampler`` and ``ProbabilitySampler``. -* **Propagator**, which is in charge of serializing and deserializing the +* **Propagator**, which serializes and deserializes the ``SpanContext`` and its headers. The default propagator is ``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, ``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``. @@ -149,8 +149,9 @@ You can customize while initializing a tracer. with tracer.span(name='child'): response = requests.get('http://localhost:5000') -You can use configuration file for Flask/Django/Pyramid. For more information, -please read the individual integration documentation `here <#integration>`_. +You can use a configuration file for Flask/Django/Pyramid. For more +information, please read the +`individual integration documentation <#integration>`_. .. code:: python diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index a802a7512..5df2b7981 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -6,14 +6,14 @@ 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 the in-process context propagation. +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 comes by default when you install OpenCensus, there is no need +This library is installed by default with `opencensus`, there is no need to install it explicitly. Usage From 73934c90def93921385a2774556db7bf4ca0b964 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 16:59:37 -0700 Subject: [PATCH 14/17] update doc --- context/opencensus-context/README.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index 5df2b7981..df3b703a2 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -19,10 +19,13 @@ to install it explicitly. Usage ----- -By default, context would flow in the same thread and async task. There are -cases where you may want to propagate the context explicitly: +In most cases, the context would just work for you automatically. This is +achieved by leveraging `threading.local()` and `contextvars`. -* Explicit thread creation: +There are cases where you may want to propagate the context explicitly: + +Explicit Thread Creation +~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: python @@ -41,7 +44,8 @@ cases where you may want to propagate the context explicitly: thread.start() thread.join() -* Thread pool: +Thread Pool +~~~~~~~~~~~ .. code:: python From 1b4f5ae830ca82b75965f61ab8505a13b005f62e Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 17:05:07 -0700 Subject: [PATCH 15/17] update doc --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 78c55c268..4a0fdbd46 100644 --- a/README.rst +++ b/README.rst @@ -103,7 +103,7 @@ Alternatively, you can explicitly start and end a span: Customization ------------- -There are several ways you can customize how OpenCensus works: +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 From 7aef5c15d2371d2718f0b6c5000c05fba8ec2295 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 18:06:38 -0700 Subject: [PATCH 16/17] update doc --- README.rst | 5 +++-- context/opencensus-context/README.rst | 7 +++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 4a0fdbd46..f73251fa5 100644 --- a/README.rst +++ b/README.rst @@ -121,8 +121,9 @@ There are several things you can customize in OpenCensus: * **Propagator**, which serializes and deserializes the ``SpanContext`` and its headers. The default propagator is - ``TraceContextPropagator``, the rest options are ``BinaryFormatPropagator``, - ``GoogleCloudFormatPropagator`` and ``TextFormatPropagator``. + ``TraceContextPropagator``, other propagators include + ``BinaryFormatPropagator``, ``GoogleCloudFormatPropagator`` and + ``TextFormatPropagator``. You can customize while initializing a tracer. diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index df3b703a2..8db64e3c9 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -19,8 +19,11 @@ to install it explicitly. Usage ----- -In most cases, the context would just work for you automatically. This is -achieved by leveraging `threading.local()` and `contextvars`. +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: From 5855b26fcdb7f5eed23537ef76061cf641894269 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Apr 2019 18:08:47 -0700 Subject: [PATCH 17/17] update doc --- context/opencensus-context/README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/context/opencensus-context/README.rst b/context/opencensus-context/README.rst index 8db64e3c9..ac17e6553 100644 --- a/context/opencensus-context/README.rst +++ b/context/opencensus-context/README.rst @@ -7,13 +7,13 @@ OpenCensus Runtime Context :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. +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 +This library is installed by default with ``opencensus``, there is no need to install it explicitly. Usage