.. raw:: html

<p align="center">
    <h1 align="center">Django GUID</h1>
</p>
<p align="center">
  <em>Now with ASGI support!</em>
</p>

.. raw:: html

<p align="center">
  <a href="https://pypi.org/pypi/django-guid">
      <img src="https://img.shields.io/pypi/v/django-guid.svg" alt="Package version">
  </a>
  <a href="https://pypi.python.org/pypi/django-guid#downloads">
      <img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Downloads">
  </a>
  <a href="https://pypi.python.org/pypi/django-guid">
      <img src="https://img.shields.io/pypi/djversions/django-guid?color=0C4B33&logo=django&logoColor=white&label=django" alt="Django versions">
  </a>
  </a>
  <a href="https://img.shields.io/badge/ASGI-supported-brightgreen.svg">
      <img src="https://img.shields.io/badge/ASGI-supported-brightgreen.svg" alt="ASGI">
  </a>
  <a href="https://img.shields.io/badge/WSGI-supported-brightgreen.svg">
      <img src="https://img.shields.io/badge/WSGI-supported-brightgreen.svg" alt="WSGI">
  </a>
</p>
<p align="center">
  <a href="https://django-guid.readthedocs.io/en/latest/?badge=latest">
      <img src="https://readthedocs.org/projects/django-guid/badge/?version=latest" alt="Docs">
  </a>

  <a href="https://codecov.io/gh/snok/django-guid">
      <img src="https://codecov.io/gh/snok/django-guid/branch/master/graph/badge.svg" alt="Codecov">
  </a>

  <a href="https://github.com/psf/black">
      <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Black">
  </a>
  <a href="https://github.com/pre-commit/pre-commit">
      <img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white" alt="Pre-commit">
  </a>
</p>

---

Django GUID attaches a unique correlation ID/request ID to all your log outputs for every request.
In other words, all logs connected to a request now has a unique ID attached to it, making debugging simple.

---

Resources:

• Free software: MIT License
• Documentation: https://django-guid.readthedocs.io
• Homepage: https://github.com/snok/django-guid

---

Examples

Log output with a GUID:

.. code-block:: flex

INFO ... [773fa6885e03493498077a273d1b7f2d] project.views This is a DRF view log, and should have a GUID.
WARNING ... [773fa6885e03493498077a273d1b7f2d] project.services.file Some warning in a function
INFO ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.views This is a DRF view log, and should have a GUID.
INFO ... [99d44111e9174c5a9494275aa7f28858] project.views This is a DRF view log, and should have a GUID.
WARNING ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.services.file Some warning in a function
WARNING ... [99d44111e9174c5a9494275aa7f28858] project.services.file Some warning in a function

Log output without a GUID:

.. code-block:: flex

INFO ... project.views This is a DRF view log, and should have a GUID.
WARNING ... project.services.file Some warning in a function
INFO ... project.views This is a DRF view log, and should have a GUID.
INFO ... project.views This is a DRF view log, and should have a GUID.
WARNING ... project.services.file Some warning in a function
WARNING ... project.services.file Some warning in a function

See the documentation <https://django-guid.readthedocs.io>_ for more examples.

---

Installation

---

Install using pip:

.. code-block:: bash

pip install django-guid

---

Settings

---

Package settings are added in your settings.py:

.. code-block:: python

DJANGO_GUID = {
    'GUID_HEADER_NAME': 'Correlation-ID',
    'VALIDATE_GUID': True,
    'RETURN_HEADER': True,
    'EXPOSE_HEADER': True,
    'INTEGRATIONS': [],
    'IGNORE_URLS': [],
    'UUID_LENGTH': 32,
}

Optional Parameters

• :code:GUID_HEADER_NAME
  The name of the GUID to look for in a header in an incoming request. Remember that it's case insensitive.

  Default: Correlation-ID

• :code:VALIDATE_GUID
  Whether the :code:GUID_HEADER_NAME should be validated or not.
  If the GUID sent to through the header is not a valid GUID (:code:uuid.uuid4).

  Default: True

• :code:RETURN_HEADER
  Whether to return the GUID (Correlation-ID) as a header in the response or not.
  It will have the same name as the :code:GUID_HEADER_NAME setting.

  Default: True

• :code:EXPOSE_HEADER
  Whether to return :code:Access-Control-Expose-Headers for the GUID header if
  :code:RETURN_HEADER is :code:True, has no effect if :code:RETURN_HEADER is :code:False.
  This is allows the JavaScript Fetch API to access the header when CORS is enabled.

  Default: True

• :code:INTEGRATIONS
  Whether to enable any custom or available integrations with :code:django_guid.
  As an example, using :code:SentryIntegration() as an integration would set Sentry's :code:transaction_id to
  match the GUID used by the middleware.

  Default: []

• :code:IGNORE_URLS
  URL endpoints where the middleware will be disabled. You can put your health check endpoints here.

  Default: []

• :code:UUID_LENGTH
  Lets you optionally trim the length of the package generated UUIDs.

  Default: 32

---

Configuration

---

Once settings have set up, add the following to your projects' settings.py:

1. Installed Apps
   =================

Add :code:django_guid to your :code:INSTALLED_APPS:

.. code-block:: python

INSTALLED_APPS = [
    ...
    'django_guid',
]

2. Middleware

Add the :code:django_guid.middleware.guid_middleware to your MIDDLEWARE:

.. code-block:: python

MIDDLEWARE = [
    'django_guid.middleware.guid_middleware',
    ...
 ]

It is recommended that you add the middleware at the top, so that the remaining middleware loggers include the requests GUID.

3. Logging Configuration
   ========================

Add :code:django_guid.log_filters.CorrelationId as a filter in your LOGGING configuration:

.. code-block:: python

LOGGING = {
    ...
    'filters': {
        'correlation_id': {
            '()': 'django_guid.log_filters.CorrelationId'
        }
    }
}

Put that filter in your handler:

.. code-block:: python

LOGGING = {
    ...
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'medium',
            'filters': ['correlation_id'],
        }
    }
}

And make sure to add the new correlation_id filter to one or all of your formatters:

.. code-block:: python

LOGGING = {
    ...
    'formatters': {
        'medium': {
            'format': '%(levelname)s %(asctime)s [%(correlation_id)s] %(name)s %(message)s'
        }
    }
}

If these settings were confusing, please have a look in the demo projects'
settings.py <https://github.com/snok/django-guid/blob/master/demoproj/settings.py>_ file for a complete example.

4. Django GUID Logger (Optional)
   ================================

If you wish to see the Django GUID middleware outputs, you may configure a logger for the module.
Simply add django_guid to your loggers in the project, like in the example below:

.. code-block:: python

LOGGING = {
    ...
    'loggers': {
        'django_guid': {
            'handlers': ['console', 'logstash'],
            'level': 'WARNING',
            'propagate': False,
        }
    }
}

This is especially useful when implementing the package, if you plan to pass existing GUIDs to the middleware, as misconfigured GUIDs will not raise exceptions, but will generate warning logs.