From f9c5e3c7177b80d9a73dbff0f069f8071c2ec4e4 Mon Sep 17 00:00:00 2001
From: Aaron Abbott <aaronabbott@google.com>
Date: Thu, 21 Apr 2022 16:11:37 +0000
Subject: [PATCH] Add entry point for x-cloud-trace-context propagator

---
 docs/cloud_trace/cloud_trace_propagator.rst   | 11 ++++++
 docs/index.rst                                |  5 +--
 opentelemetry-propagator-gcp/setup.cfg        |  4 +++
 .../cloud_trace_propagator/__init__.py        | 33 +++++++++++++++++-
 ..._cloud_trace_propagator_auto_instrument.py | 34 +++++++++++++++++++
 5 files changed, 84 insertions(+), 3 deletions(-)
 create mode 100644 docs/cloud_trace/cloud_trace_propagator.rst
 create mode 100644 opentelemetry-propagator-gcp/tests/test_cloud_trace_propagator_auto_instrument.py

diff --git a/docs/cloud_trace/cloud_trace_propagator.rst b/docs/cloud_trace/cloud_trace_propagator.rst
new file mode 100644
index 00000000..ca58c66b
--- /dev/null
+++ b/docs/cloud_trace/cloud_trace_propagator.rst
@@ -0,0 +1,11 @@
+OpenTelemetry Cloud Trace Propagator
+==================================
+
+.. image:: https://badge.fury.io/py/opentelemetry-propagator-gcp.svg
+    :target: https://badge.fury.io/py/opentelemetry-propagator-gcp
+
+.. automodule:: opentelemetry.propagators.cloud_trace_propagator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
diff --git a/docs/index.rst b/docs/index.rst
index 98dd56fc..c9e27b16 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -49,9 +49,10 @@ To install the GCP trace propagator:
    :maxdepth: 1
    :caption: Exporters
    :name: exporters
+   :glob:
 
-   cloud_monitoring/cloud_monitoring
-   cloud_trace/cloud_trace
+   cloud_monitoring/**
+   cloud_trace/**
 
 
 .. toctree::
diff --git a/opentelemetry-propagator-gcp/setup.cfg b/opentelemetry-propagator-gcp/setup.cfg
index 8f37e51f..03d25048 100644
--- a/opentelemetry-propagator-gcp/setup.cfg
+++ b/opentelemetry-propagator-gcp/setup.cfg
@@ -32,3 +32,7 @@ where = src
 
 [options.extras_require]
 test =
+
+[options.entry_points]
+opentelemetry_propagator =
+    gcp_trace = opentelemetry.propagators.cloud_trace_propagator:CloudTraceFormatPropagator
diff --git a/opentelemetry-propagator-gcp/src/opentelemetry/propagators/cloud_trace_propagator/__init__.py b/opentelemetry-propagator-gcp/src/opentelemetry/propagators/cloud_trace_propagator/__init__.py
index bae14af5..f2ebadf3 100644
--- a/opentelemetry-propagator-gcp/src/opentelemetry/propagators/cloud_trace_propagator/__init__.py
+++ b/opentelemetry-propagator-gcp/src/opentelemetry/propagators/cloud_trace_propagator/__init__.py
@@ -11,7 +11,38 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-#
+
+"""Cloud Trace Span Propagator for X-Cloud-Trace-Context format.
+
+Usage
+-----
+
+.. 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())
+
+Auto-instrumentation
+--------------------
+
+This exporter can also be used with the :envvar:`OTEL_PROPAGATORS` environment variable as
+``OTEL_PROPAGATORS=gcp_trace``.
+
+This also works with `OpenTelemetry auto-instrumentation
+<https://opentelemetry.io/docs/instrumentation/python/automatic/>`_:
+
+.. code-block:: sh
+
+    opentelemetry-instrument --propagator gcp_trace <command> <args>
+
+API
+---
+"""
 
 import re
 import typing
diff --git a/opentelemetry-propagator-gcp/tests/test_cloud_trace_propagator_auto_instrument.py b/opentelemetry-propagator-gcp/tests/test_cloud_trace_propagator_auto_instrument.py
new file mode 100644
index 00000000..e7020813
--- /dev/null
+++ b/opentelemetry-propagator-gcp/tests/test_cloud_trace_propagator_auto_instrument.py
@@ -0,0 +1,34 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from unittest import TestCase
+from unittest.mock import patch
+
+from opentelemetry.environment_variables import OTEL_PROPAGATORS
+from opentelemetry.propagators.cloud_trace_propagator import (
+    CloudTraceFormatPropagator,
+)
+
+
+class TestCloudTracePropagatorAutoInstrument(TestCase):
+    @patch.dict("os.environ", {OTEL_PROPAGATORS: "gcp_trace"})
+    def test_loads_cloud_trace_propagator(self):
+        # This test is a bit fragile as the propagator entry points are loaded on the first
+        # import of opentelemetry.propagate and saved in a global variable. If another tests
+        # imports that before this one, it can fail.
+        # pylint: disable=import-outside-toplevel
+        from opentelemetry.propagate import propagators
+
+        self.assertEqual(len(propagators), 1)
+        self.assertIsInstance(propagators[0], CloudTraceFormatPropagator)