Merge pull request #366 from DataDog/benjamin/distributed-django

Add distributed sampling support to Django

Author: LotharSee

ddtrace/contrib/django/__init__.py

@@ -44,6 +44,11 @@
   are sent to the trace agent. This setting cannot be changed at runtime
   and a restart is required. By default the tracer is disabled when in ``DEBUG``
   mode, enabled otherwise.
+* ``DISTRIBUTED_TRACING`` (default: ``False``): defines if the tracer should
+  use incoming X-DATADOG-* HTTP headers to extend a trace created remotely. It is
+  required for distributed tracing if this application is called remotely from another
+  instrumented application.
+  We suggest to enable it only for internal services where headers are under your control.
 * ``AGENT_HOSTNAME`` (default: ``localhost``): define the hostname of the trace agent.
 * ``AGENT_PORT`` (default: ``8126``): define the port of the trace agent.
 * ``AUTO_INSTRUMENT`` (default: ``True``): if set to false the code will not be

ddtrace/contrib/django/conf.py

@@ -34,6 +34,7 @@
     'DEFAULT_DATABASE_PREFIX': '',
     'DEFAULT_SERVICE': 'django',
     'ENABLED': True,
+    'DISTRIBUTED_TRACING': False,
     'TAGS': {},
     'TRACER': 'ddtrace.tracer',
 }

ddtrace/contrib/django/middleware.py

@@ -5,6 +5,7 @@
 
 from ...ext import http
 from ...contrib import func_name
+from ...propagation.http import HTTPPropagator
 
 # 3p
 from django.core.exceptions import MiddlewareNotUsed
@@ -80,6 +81,12 @@ class TraceMiddleware(InstrumentationMixin):
     """
     def process_request(self, request):
         tracer = settings.TRACER
+        if settings.DISTRIBUTED_TRACING:
+            propagator = HTTPPropagator()
+            context = propagator.extract(request.META)
+            # Only need to active the new context if something was propagated
+            if context.trace_id:
+                tracer.context_provider.activate(context)
         try:
             span = tracer.trace(
                 'django.request',

ddtrace/propagation/http.py

@@ -39,11 +39,11 @@ def extract(self, headers):
 
             from ddtrace.propagation.http import HTTPPropagator
 
-            def child_call(url, headers):
+            def my_controller(url, headers):
                 context = HTTPPropagator.extract(headers)
                 tracer.context_provider.activate(context)
 
-                with tracer.trace("child_span") as span:
+                with tracer.trace("my_controller") as span:
                     span.set_meta('http.url', url)
 
         :param dict headers: HTTP headers to extract tracing attributes.

docs/index.rst

@@ -272,13 +272,25 @@ Distributed Tracing
 
 To trace requests across hosts, the spans on the secondary hosts must be linked together by setting `trace_id`, `parent_id` and `sampling_priority`.
 
+- On the server side, it means to read propagated attributes and set them to the active tracing context.
+- On the client side, it means to propagate the attributes, commonly as a header/metadata.
+
 `ddtrace` already provides default propagators but you can also implement your own.
 
-HTTP
-~~~~
+Web frameworks
+~~~~~~~~~~~~~~
+
+Some web framework integrations support the distributed tracing out of the box, you just have to enable it.
+For that, refer to the configuration of the given integration.
+Supported web frameworks:
+
+- Django
+
+
+HTTP client/server
+~~~~~~~~~~~~~~~~~~
 
-The `HTTPPropagator` is already automatically used in our `aiohttp` integration. For the others, you can use
-it manually.
+You can use the `HTTPPropagator` manually when used with an HTTP client or if your web framework isn't supported.
 
 .. autoclass:: ddtrace.propagation.http.HTTPPropagator
     :members:

tests/contrib/django/test_middleware.py

@@ -5,11 +5,12 @@
 from django.core.urlresolvers import reverse
 
 # project
+from ddtrace.constants import SAMPLING_PRIORITY_KEY
 from ddtrace.contrib.django.conf import settings
 from ddtrace.contrib.django import TraceMiddleware
 
 # testing
-from .utils import DjangoTraceTestCase
+from .utils import DjangoTraceTestCase, override_ddtrace_settings
 
 
 class DjangoMiddlewareTest(DjangoTraceTestCase):
@@ -143,3 +144,50 @@ def test_middleware_without_user(self):
         sp_database = spans[2]
         eq_(sp_request.get_tag('http.status_code'), '200')
         eq_(sp_request.get_tag('django.user.is_authenticated'), None)
+
+    @override_ddtrace_settings(DISTRIBUTED_TRACING=True)
+    def test_middleware_propagation(self):
+        # ensures that we properly propagate http context
+        url = reverse('users-list')
+        headers = {
+            'x-datadog-trace-id': '100',
+            'x-datadog-parent-id': '42',
+            'x-datadog-sampling-priority': '2',
+        }
+        response = self.client.get(url, **headers)
+        eq_(response.status_code, 200)
+
+        # check for spans
+        spans = self.tracer.writer.pop()
+        eq_(len(spans), 3)
+        sp_request = spans[0]
+        sp_template = spans[1]
+        sp_database = spans[2]
+
+        # Check for proper propagated attributes
+        eq_(sp_request.trace_id, 100)
+        eq_(sp_request.parent_id, 42)
+        eq_(sp_request.get_metric(SAMPLING_PRIORITY_KEY), 2)
+
+    def test_middleware_no_propagation(self):
+        # ensures that we properly propagate http context
+        url = reverse('users-list')
+        headers = {
+            'x-datadog-trace-id': '100',
+            'x-datadog-parent-id': '42',
+            'x-datadog-sampling-priority': '2',
+        }
+        response = self.client.get(url, **headers)
+        eq_(response.status_code, 200)
+
+        # check for spans
+        spans = self.tracer.writer.pop()
+        eq_(len(spans), 3)
+        sp_request = spans[0]
+        sp_template = spans[1]
+        sp_database = spans[2]
+
+        # Check that propagation didn't happen
+        assert sp_request.trace_id != 100
+        assert sp_request.parent_id != 42
+        assert sp_request.get_metric(SAMPLING_PRIORITY_KEY) != 2