[django] provide a Django app (#67) from palazzem/django-app-conversion

Author: Emanuele Palazzetti

ddtrace/contrib/django/__init__.py

@@ -1,26 +1,63 @@
 """
-The Django middleware will trace requests, database calls and template
+The Django integration will trace requests, database calls and template
 renders.
 
 To install the Django tracing middleware, add it to the list of your
-application's installed in middleware in settings.py::
+installed apps and in your middleware classes in ``settings.py``::
 
+    INSTALLED_APPS = [
+        # ...
+
+        # the order is not important
+        'ddtrace.contrib.django',
+    ]
 
     MIDDLEWARE_CLASSES = (
-        ...
+        # the tracer must be the first middleware
         'ddtrace.contrib.django.TraceMiddleware',
         ...
     )
 
-    DATADOG_SERVICE = 'my-app'
+The configuration of this integration is all namespaced inside a single
+Django setting, named ``DATADOG_TRACE``. For example, your ``settings.py``
+may contain::
 
-"""
+    DATADOG_TRACE = {
+        'DEFAULT_SERVICE': 'my-django-app',
+    }
+
+If you need to access to the tracing settings, you should::
+
+    from ddtrace.contrib.django.conf import settings
+
+    tracer = settings.TRACER
+    tracer.trace("something")
+    # your code ...
 
+The available settings are:
+
+* ``TRACER`` (default ``ddtrace.tracer``): set the default tracer
+  instance that is used to trace Django internals. By default the ``ddtrace``
+  tracer is used.
+* ``DEFAULT_SERVICE`` (default: ``django``): set the service name used by the
+  tracer. Usually this configuration must be updated with a meaningful name.
+* ``ENABLED``: (default: ``not django_settings.DEBUG``): set if the tracer
+  is enabled or not. When a tracer is disabled, Django internals are not
+  automatically instrumented and the requests are not traced even if the
+  ``TraceMiddleware`` is properly installed. This settings cannot be changed
+  at runtime and a restart is required. By default the tracer is disabled
+  when in ``DEBUG`` mode, enabled otherwise.
+"""
 from ..util import require_modules
 
+
 required_modules = ['django']
 
 with require_modules(required_modules) as missing_modules:
     if not missing_modules:
         from .middleware import TraceMiddleware
         __all__ = ['TraceMiddleware']
+
+
+# define the Django app configuration
+default_app_config = 'ddtrace.contrib.django.apps.TracerConfig'

ddtrace/contrib/django/apps.py

@@ -0,0 +1,45 @@
+import logging
+
+# 3rd party
+from django.apps import AppConfig
+
+# project
+from .db import patch_db
+from .conf import settings
+from .templates import patch_template
+
+from ...ext import AppTypes
+
+
+log = logging.getLogger(__name__)
+
+
+class TracerConfig(AppConfig):
+    name = 'ddtrace.contrib.django'
+
+    def ready(self):
+        """
+        Ready is called as soon as the registry is fully populated.
+        Tracing capabilities must be enabled in this function so that
+        all Django internals are properly configured.
+        """
+        if settings.ENABLED:
+            tracer = settings.TRACER
+
+            # define the service details
+            tracer.set_service_info(
+                service=settings.DEFAULT_SERVICE,
+                app='django',
+                app_type=AppTypes.web,
+            )
+
+            # trace Django internals
+            try:
+                patch_db(tracer)
+            except Exception:
+                log.exception('error patching Django database connections')
+
+            try:
+                patch_template(tracer)
+            except Exception:
+                log.exception('error patching Django template rendering')

ddtrace/contrib/django/conf.py

@@ -0,0 +1,125 @@
+"""
+Settings for Datadog tracer are all namespaced in the DATADOG_TRACE setting.
+For example your project's `settings.py` file might look like this:
+
+DATADOG_TRACE = {
+    'TRACER': 'myapp.tracer',
+}
+
+This module provides the `setting` object, that is used to access
+Datadog settings, checking for user settings first, then falling
+back to the defaults.
+"""
+from __future__ import unicode_literals
+
+import importlib
+
+from django.conf import settings as django_settings
+
+from django.test.signals import setting_changed
+
+
+USER_SETTINGS = getattr(django_settings, 'DATADOG_TRACE', None)
+
+# List of available settings with their defaults
+DEFAULTS = {
+    'TRACER': 'ddtrace.tracer',
+    'DEFAULT_SERVICE': 'django',
+    'ENABLED': not django_settings.DEBUG,
+}
+
+# List of settings that may be in string import notation.
+IMPORT_STRINGS = (
+    'TRACER',
+)
+
+# List of settings that have been removed
+REMOVED_SETTINGS = ()
+
+
+def import_from_string(val, setting_name):
+    """
+    Attempt to import a class from a string representation.
+    """
+    try:
+        # Nod to tastypie's use of importlib.
+        parts = val.split('.')
+        module_path, class_name = '.'.join(parts[:-1]), parts[-1]
+        module = importlib.import_module(module_path)
+        return getattr(module, class_name)
+    except (ImportError, AttributeError) as e:
+        msg = 'Could not import "{}" for setting "{}". {}: {}.'.format(
+                val, setting_name,
+                e.__class__.__name__, e
+        )
+
+        raise ImportError(msg)
+
+
+class DatadogSettings(object):
+    """
+    A settings object, that allows Datadog settings to be accessed as properties.
+    For example:
+
+        from ddtrace.contrib.django.conf import settings
+
+        tracer = settings.TRACER
+
+    Any setting with string import paths will be automatically resolved
+    and return the class, rather than the string literal.
+    """
+    def __init__(self, user_settings=None, defaults=None, import_strings=None):
+        if user_settings:
+            self._user_settings = self.__check_user_settings(user_settings)
+        self.defaults = defaults or DEFAULTS
+        self.import_strings = import_strings or IMPORT_STRINGS
+
+    @property
+    def user_settings(self):
+        if not hasattr(self, '_user_settings'):
+            self._user_settings = getattr(settings, 'DATADOG_TRACE', {})
+        return self._user_settings
+
+    def __getattr__(self, attr):
+        if attr not in self.defaults:
+            raise AttributeError('Invalid setting: "{}"'.format(attr))
+
+        try:
+            # Check if present in user settings
+            val = self.user_settings[attr]
+        except KeyError:
+            # Otherwise, fall back to defaults
+            val = self.defaults[attr]
+
+        # Coerce import strings into classes
+        if attr in self.import_strings:
+            val = import_from_string(val, attr)
+
+        # Cache the result
+        setattr(self, attr, val)
+        return val
+
+    def __check_user_settings(self, user_settings):
+        SETTINGS_DOC = 'http://pypi.datadoghq.com/trace-dev/docs/#module-ddtrace.contrib.django'
+        for setting in REMOVED_SETTINGS:
+            if setting in user_settings:
+                raise RuntimeError(
+                    'The "{}" setting has been removed, check "{}".'.format(setting, SETTINGS_DOC)
+                )
+        return user_settings
+
+
+settings = DatadogSettings(USER_SETTINGS, DEFAULTS, IMPORT_STRINGS)
+
+
+def reload_settings(*args, **kwargs):
+    """
+    Triggers a reload when Django emits the reloading signal
+    """
+    global settings
+    setting, value = kwargs['setting'], kwargs['value']
+    if setting == 'DATADOG_TRACE':
+        settings = DatadogSettings(value, DEFAULTS, IMPORT_STRINGS)
+
+
+setting_changed.connect(reload_settings)

ddtrace/contrib/django/middleware.py

@@ -1,59 +1,44 @@
 import logging
 
 # project
-from ...ext import http, AppTypes
-from ...contrib import func_name
+from .conf import settings
 
-from .db import patch_db
-from .settings import import_from_string
-from .templates import patch_template
+from ...ext import http
+from ...contrib import func_name
 
 # 3p
 from django.apps import apps
-from django.conf import settings
+from django.core.exceptions import MiddlewareNotUsed
 
 
 log = logging.getLogger(__name__)
 
 
 class TraceMiddleware(object):
+    """
+    Middleware that traces Django requests
+    """
     def __init__(self):
-        # TODO[manu]: maybe we can formalize better DJANGO_SETTINGS_* stuff
-        # providing defaults or raise ImproperlyConfigured errors
-        tracer_import = getattr(settings, 'DATADOG_TRACER', 'ddtrace.tracer')
-        self.tracer = import_from_string(tracer_import, 'DATADOG_TRACER')
-        self.service = getattr(settings, 'DATADOG_SERVICE', 'django')
-
-        self.tracer.set_service_info(
-            service=self.service,
-            app='django',
-            app_type=AppTypes.web,
-        )
-
-        try:
-            # TODO[manu]: maybe it's better to provide a Django app that
-            # will patch everything once instead of trying that for
-            # each request (in the case of patch_db)?
-            patch_template(self.tracer)
-        except Exception:
-            log.exception("error patching template class")
+        # disable the middleware if the tracer is not enabled
+        if not settings.ENABLED:
+            raise MiddlewareNotUsed
 
     def process_request(self, request):
-        try:
-            patch_db(self.tracer)  # ensure that connections are always patched.
+        tracer = settings.TRACER
 
-            span = self.tracer.trace(
-                "django.request",
-                service=self.service,
-                resource="unknown",  # will be filled by process view
+        try:
+            span = tracer.trace(
+                'django.request',
+                service=settings.DEFAULT_SERVICE,
+                resource='unknown',  # will be filled by process view
                 span_type=http.TYPE,
             )
 
             span.set_tag(http.METHOD, request.method)
             span.set_tag(http.URL, request.path)
             _set_req_span(request, span)
         except Exception:
-            log.exception("error tracing request")
+            log.exception('error tracing request')
 
     def process_view(self, request, view_func, *args, **kwargs):
         span = _get_req_span(request)

ddtrace/contrib/django/settings.py

@@ -20,7 +20,7 @@
 USE_I18N = True
 USE_L10N = True
 STATIC_URL = '/static/'
-ROOT_URLCONF = 'app.views'
+ROOT_URLCONF = 'tests.contrib.django.app.views'
 
 TEMPLATES = [
     {
@@ -41,6 +41,9 @@
 ]
 
 MIDDLEWARE_CLASSES = [
+    # tracer middleware
+    'ddtrace.contrib.django.TraceMiddleware',
+
     'django.contrib.sessions.middleware.SessionMiddleware',
     'django.middleware.common.CommonMiddleware',
     'django.middleware.csrf.CsrfViewMiddleware',
@@ -56,4 +59,13 @@
     'django.contrib.auth',
     'django.contrib.contenttypes',
     'django.contrib.sessions',
+
+    # tracer app
+    'ddtrace.contrib.django',
 ]
+
+DATADOG_TRACE = {
+    # tracer with a DummyWriter
+    'TRACER': 'tests.contrib.django.utils.tracer',
+    'ENABLED': True,
+}

tests/contrib/django/app/settings.py

@@ -4,8 +4,16 @@
 
 
 if __name__ == "__main__":
+    # define django defaults
     app_to_test = "tests/contrib/django"
     os.environ.setdefault("DJANGO_SETTINGS_MODULE", "app.settings")
 
+    # append the project root to the PYTHONPATH:
+    # this is required because we don't want to put the current file
+    # in the project_root
+    current_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    project_root = os.path.join(current_dir, '..', '..')
+    sys.path.append(project_root)
+
     from django.core.management import execute_from_command_line
     execute_from_command_line([sys.argv[0], "test", app_to_test])