docs: update datadog docs (open-telemetry#803)

majorgreys · web-flow · commit 0b823a19d2e2 · 2020-06-14T23:03:30.000-07:00
Update the Datadog docs for installation and using propagation.
diff --git a/docs/examples/datadog_exporter/README.rst b/docs/examples/datadog_exporter/README.rst
@@ -32,10 +32,15 @@ Basic Example
 
 .. code-block:: sh
 
-    python datadog_exporter.py
+    python basic_example.py
 
-Auto-Instrumention Example
---------------------------
+
+.. code-block:: sh
+
+    python basic_example.py
+
+Distributed Example
+-------------------
 
 * Installation
 
@@ -79,3 +84,12 @@ Auto-Instrumention Example
 .. code-block:: sh
 
     opentelemetry-instrument python client.py error
+
+* Run Datadog instrumented client
+
+The OpenTelemetry instrumented server is set up with propagation of Datadog trace context.
+
+.. code-block:: sh
+
+    pip install ddtrace
+    ddtrace-run python datadog_client.py testing
diff --git a/docs/examples/datadog_exporter/basic_example.py b/docs/examples/datadog_exporter/basic_example.py
@@ -31,6 +31,7 @@
 span_processor = DatadogExportSpanProcessor(exporter)
 trace.get_tracer_provider().add_span_processor(span_processor)
 
+
 with tracer.start_as_current_span("foo"):
     with tracer.start_as_current_span("bar"):
         with tracer.start_as_current_span("baz"):
diff --git a/docs/examples/datadog_exporter/datadog_client.py b/docs/examples/datadog_exporter/datadog_client.py
@@ -0,0 +1,23 @@
+# Copyright The OpenTelemetry Authors
+#
+# 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
+#
+#     http://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 sys import argv
+
+import requests
+
+requested = requests.get(
+    "http://localhost:8082/server_request", params={"param": argv[1]}
+)
+assert requested.status_code == 200
+print(requested.text)
diff --git a/docs/examples/datadog_exporter/server.py b/docs/examples/datadog_exporter/server.py
@@ -14,11 +14,12 @@
 
 from flask import Flask, request
 
-from opentelemetry import trace
+from opentelemetry import propagators, trace
 from opentelemetry.ext.datadog import (
     DatadogExportSpanProcessor,
     DatadogSpanExporter,
 )
+from opentelemetry.ext.datadog.propagator import DatadogFormat
 from opentelemetry.sdk.trace import TracerProvider
 
 app = Flask(__name__)
@@ -33,6 +34,21 @@
     )
 )
 
+# append Datadog format for propagation to and from Datadog instrumented services
+global_httptextformat = propagators.get_global_httptextformat()
+if isinstance(
+    global_httptextformat, propagators.composite.CompositeHTTPPropagator
+) and not any(
+    isinstance(p, DatadogFormat) for p in global_httptextformat._propagators
+):
+    propagators.set_global_httptextformat(
+        propagators.composite.CompositeHTTPPropagator(
+            global_httptextformat._propagators + [DatadogFormat()]
+        )
+    )
+else:
+    propagators.set_global_httptextformat(DatadogFormat())
+
 tracer = trace.get_tracer(__name__)
 
 
diff --git a/ext/opentelemetry-ext-datadog/src/opentelemetry/ext/datadog/__init__.py b/ext/opentelemetry-ext-datadog/src/opentelemetry/ext/datadog/__init__.py
@@ -16,13 +16,27 @@
 The **OpenTelemetry Datadog Exporter** provides a span exporter from
 `OpenTelemetry`_ traces to `Datadog`_ by using the Datadog Agent.
 
+Installation
+------------
+
+::
+
+    pip install opentelemetry-ext-datadog
+
+
 Usage
 -----
 
+The Datadog exporter provides a span processor that must be added along with the
+exporter. In addition, a formatter is provided to handle propagation of trace
+context between OpenTelemetry-instrumented and Datadog-instrumented services in
+a distributed trace.
+
 .. code:: python
 
-    from opentelemetry import trace
+    from opentelemetry import propagators, trace
     from opentelemetry.ext.datadog import DatadogExportSpanProcessor, DatadogSpanExporter
+    from opentelemetry.ext.datadog.propagator import DatadogFormat
     from opentelemetry.sdk.trace import TracerProvider
 
     trace.set_tracer_provider(TracerProvider())
@@ -35,13 +49,24 @@
     span_processor = DatadogExportSpanProcessor(exporter)
     trace.get_tracer_provider().add_span_processor(span_processor)
 
+    # Optional: use Datadog format for propagation in distributed traces
+    propagators.set_global_httptextformat(DatadogFormat())
+
     with tracer.start_as_current_span("foo"):
         print("Hello world!")
 
+
+Examples
+--------
+
+The `docs/examples/datadog_exporter`_ includes examples for using the Datadog
+exporter with OpenTelemetry instrumented applications.
+
 API
 ---
 .. _Datadog: https://www.datadoghq.com/
 .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
+.. _docs/examples/datadog_exporter: https://github.com/open-telemetry/opentelemetry-python/tree/master/docs/examples/datadog_exporter
 """
 # pylint: disable=import-error
 
