Create a Readonly Propagator to match the golang "One Way" propagator. (#196)

* Create a Readonly Propagator to match the golang "One Way" propagator.

Also adds usage information to README.rst for both propagators.

* lint fix

* Rename "Readonly" to "OneWay" for consistency with other languages

also corrects a type error with an empty set.

* style fix from @aabmass

Co-authored-by: Aaron Abbott <[email protected]>

Co-authored-by: Aaron Abbott <[email protected]>

Author: muncus

opentelemetry-propagator-gcp/README.rst

@@ -18,8 +18,52 @@ Installation
 
     pip install opentelemetry-propagator-gcp
 
-..
-    TODO: Add usage info here
+Usage
+-----
+
+The ``CloudTraceOneWayPropagator`` reads the Google Cloud
+``X-Cloud-Trace-Context`` format, but does not write the
+``X-Cloud-Trace-Context`` header on outgoing requests. It is intended for use
+with a CompositePropagator as below.
+
+.. code-block:: python
+
+    from opentelemetry.propagate import set_global_textmap
+    from opentelemetry.propagators.composite import CompositePropagator
+    from opentelemetry.propagators.cloud_trace_propagator import (
+        CloudTraceOneWayPropagator,
+    )
+    set_global_textmap(
+        CompositePropagator([
+            CloudTraceOneWayPropagator(),
+            propagate.get_global_textmap(),
+        ]),
+    )
+
+The ``CloudTraceFormatPropagator`` reads and writes the
+``X-Cloud-Trace-Context`` header formats. Note that when using this propagator,
+the ``sampled`` bit is interpreted as the ``TRACE_TRUE`` flag, which may cause a
+higher sampling rate than desired. See the `Trace documentation
+<https://cloud.google.com/trace/docs/setup#force-trace>` for additional context.
+
+.. code-block:: python
+
+    from opentelemetry.propagate import set_global_textmap
+    from opentelemetry.propagators.cloud_trace_propagator import (
+        CloudTraceFormatPropagator,
+    )
+
+    # Set the X-Cloud-Trace-Context header
+    set_global_textmap(CloudTraceFormatPropagator())
+.. code-block:: python
+
+    from opentelemetry.propagate import set_global_textmap
+    from opentelemetry.propagators.cloud_trace_propagator import (
+        CloudTraceFormatPropagator,
+    )
+
+    # Set the X-Cloud-Trace-Context header
+    set_global_textmap(CloudTraceFormatPropagator())
 
 
 References

opentelemetry-propagator-gcp/src/opentelemetry/propagators/cloud_trace_propagator/__init__.py

@@ -138,3 +138,22 @@ def inject(
     @property
     def fields(self) -> typing.Set[str]:
         return _FIELDS
+
+
+class CloudTraceOneWayPropagator(CloudTraceFormatPropagator):
+    """This class extracts Trace Context in the Google Cloud format, but does
+    not inject this header. It is intended for use in a Composite Propagator to
+    inject context in a different format than was received.
+    """
+
+    def inject(
+        self,
+        carrier: textmap.CarrierT,
+        context: typing.Optional[Context] = None,
+        setter: textmap.Setter = textmap.default_setter,
+    ) -> None:
+        return
+
+    @property
+    def fields(self) -> typing.Set[str]:
+        return set()