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

<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:

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:

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 for more examples.

Installation

Install using pip:

pip install django-guid

Settings

Package settings are added in your settings.py:

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

Optional Parameters

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
```
VALIDATE_GUID

Whether the GUID_HEADER_NAME should be validated or not. If the GUID sent to through the header is not a valid GUID (uuid.uuid4).
```
Default: True
```
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 GUID_HEADER_NAME setting.
```
Default: True
```
EXPOSE_HEADER

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

Whether to enable any custom or available integrations with django_guid. As an example, using SentryIntegration() as an integration would set Sentry\'s transaction_id to match the GUID used by the middleware.
```
Default: \[\]
```
IGNORE_URLS

URL endpoints where the middleware will be disabled. You can put your health check endpoints here.
```
Default: \[\]
```
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 django_guid to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'django_guid',
]

2. Middleware

Add the django_guid.middleware.guid_middleware to your MIDDLEWARE:

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 django_guid.log_filters.CorrelationId as a filter in your LOGGING configuration:

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

Put that filter in your handler:

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:

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 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:

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.