.. raw:: html
Django GUID
Now with ASGI support!
.. raw:: html
--------------
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 `_ 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 `_ 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.