Add CID_GENERATOR setting to specify a custom generator

HISTORY.rst

@@ -6,6 +6,8 @@ History
 
 * |backward-incompatible| Drop support of Python 3.4.
 * |backward-incompatible| Drop support of Django 1.11 and Django 2.0.
+* Add ``CID_GENERATOR`` setting to allow the customization of the
+  correlation id.
 
 
 1.3 (2018-10-09)

cid/locals.py

@@ -23,18 +23,23 @@ def get_cid():
     """
     cid = getattr(_thread_locals, 'CID', None)
     if cid is None and getattr(settings, 'CID_GENERATE', False):
-        cid = str(uuid.uuid4())
+        cid = _build_cid()
         set_cid(cid)
     return cid
 
 
 def generate_new_cid(upstream_cid=None):
     """Generate a new correlation id, possibly based on the given one."""
     if upstream_cid is None:
-        return str(uuid.uuid4()) if getattr(settings, 'CID_GENERATE', False) else None
+        return _build_cid() if getattr(settings, 'CID_GENERATE', False) else None
     if (
             getattr(settings, 'CID_CONCATENATE_IDS', False)
             and getattr(settings, 'CID_GENERATE', False)
     ):
-        return '%s, %s' % (upstream_cid, str(uuid.uuid4()))
+        return '%s, %s' % (upstream_cid, _build_cid())
     return upstream_cid
+
+
+def _build_cid():
+    """Build a new cid"""
+    return str(getattr(settings, 'CID_GENERATOR', uuid.uuid4)())

docs/installation.rst

@@ -37,9 +37,18 @@ the settings:
 
     CID_GENERATE = True
 
-This approach is perfectly acceptable but does suffer one drawback. If
-you host your Django application behind another web server such as
-nginx, then nginx logs won't contain the correlation id.
+By default, ``django-cid`` uses ``str(uuid.uuid4())`` to generate the
+correlation id but you can customize this generation to suit your
+needs in the settings:
+
+.. code-block:: python
+
+    CID_GENERATOR = lambda: f'{time.time()}-{random.random()}'
+
+Letting ``django-cid`` generate a new correlation id is perfectly
+acceptable but does suffer one drawback. If you host your Django
+application behind another web server such as nginx, then nginx logs
+won't contain the correlation id.
 ``django-cid`` can handle this by extracting a correlation id created
 in nginx and passed through as a header in the HTTP request. For this
 to work, you must enable a middleware in the settings, like this:

tests/test_locals.py

@@ -1,6 +1,6 @@
-from django.test import TestCase
+from django.test import TestCase, override_settings
 from threading import local
-from cid.locals import get_cid, set_cid
+from cid.locals import get_cid, set_cid, generate_new_cid
 
 
 _thread_locals = local()
@@ -28,3 +28,7 @@ def test_set_cid(self):
         self.assertIsNone(get_cid())
         set_cid(self.cid)
         self.assertEqual(self.cid, get_cid())
+
+    @override_settings(CID_GENERATE=True, CID_GENERATOR=lambda: 'constant_correlation')
+    def test_custom_generator(self):
+        assert generate_new_cid() == 'constant_correlation'