Middleware that makes a request GUID available from anywhere and injects it into your logs.
Project description
Django GUID
Django GUID stores a GUID to an object, making it accessible by using the ID of the current thread. The GUID is accessible from anywhere within the application throughout a request, allowing us to inject it into the logs.
Free software: BSD License
Homepage: https://github.com/JonasKs/django-guid
Documentation: https://django-guid.readthedocs.io
Example
Using demoproj as an example, all the log messages without django-guid would look like this:
INFO 2020-01-14 12:28:42,194 django_guid.middleware No Correlation-ID found in the header. Added Correlation-ID: 97c304252fd14b25b72d6aee31565843
INFO 2020-01-14 12:28:42,353 demoproj.views This is a DRF view log, and should have a GUID.
INFO 2020-01-14 12:28:42,354 demoproj.services.useless_file Some warning in a function
With django-guid every log message has a GUID attached to it(97c304252fd14b25b72d6aee31565843), through the entire stack:
INFO 2020-01-14 12:28:42,194 [None] django_guid.middleware No Correlation-ID found in the header. Added Correlation-ID: 97c304252fd14b25b72d6aee31565843
INFO 2020-01-14 12:28:42,353 [97c304252fd14b25b72d6aee31565843] demoproj.views This is a DRF view log, and should have a GUID.
INFO 2020-01-14 12:28:42,354 [97c304252fd14b25b72d6aee31565843] demoproj.services.useless_file Some warning in a function
For multiple requests at the same time over multiple threads, see the extended example docs.
Why
django-guid makes it extremely easy to track exactly what happened in any request. If you see an error in your log, you can use the attached GUID to search for any connected log message to that single request. The GUID can also be returned as a header and displayed to the end user of your application, allowing them to report an issue with a connected ID. django-guid makes troubleshooting easy.
Settings
SKIP_CLEANUP
After the request is done, the GUID is deleted to avoid memory leaks. Memory leaks can happen in the case of many threads, or especially when using Gunicorn
max_requests
or similar settings, where the number of thread IDs can potentially scale for ever. Having clean up enabled ensures we can not have memory leaks, but comes at the cost that anything that happens after this middleware will not have the GUID attached, such asdjango.request
ordjango.server
logs. If you do not want clean up of GUIDs and know what you’re doing, you can enableSKIP_CLEANUP
.Default: False
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
RETURN_HEADER
Whether to return
Access-Control-Expose-Headers
for the GUID header ifRETURN_HEADER
isTrue
, has no effect ifRETURN_HEADER
isFalse
. This is allows the JavaScript Fetch API to access the header when CORS is enabled.Default: True
Installation
Install using pip:
pip install django-guid
Then, in your project’s settings.py
add these settings:
Add the middleware to the MIDDLEWARE
setting (if you want the correlation-ID to span your middleware-logs, put it on top):
MIDDLEWARE = [
'django_guid.middleware.GuidMiddleware',
...
]
Add a filter to your LOGGING:
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'],
}
}
}
Lastly make sure we add the new correlation_id filter to the 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 project’s settings.py file for a complete example.
If you wish to aggregate the django-guid logs to your console or other handlers, add django_guid to your loggers in the project. Example:
LOGGING = {
...
'loggers': {
'django_guid': {
'handlers': ['console', 'logstash'],
'level': 'WARNING',
'propagate': False,
}
}
}
Inspired by django-log-request-id with a complete rewritten django-echelon approach.
Changelog
1.1.0 - 2020-02-10
Features
Added a EXPOSE_HEADER setting, which will add the Access-Control-Expose-Headers with the RETURN_HEADER as value to the response. This is to allow the JavaScript Fetch API to access the header with the GUID
1.0.1 - 2020-02-08
Bugfix
Fixed validation of incoming GUID
Improvements
Changed the middleware.py logger name to django_guid
Added a WARNING-logger for when validation fails
Improved README
Other
Added CONTRIBUTORS.rst
1.0.0 - 2020-01-14
Features
Added a RETURN_HEADER setting, which will return the GUID as a header with the same name
Improvements
Added a Django Rest Framework test and added DRF to the demoproj
Improved tests to also check for headers in the response
Added tests for the new setting
Added examples to README.rst and docs, to show how the log messages get formatted
Added an API page to the docs
Fixed the readthedocs menu bug
0.3.1 - 2020-01-13
Improvements
Changed logging from f’strings’ to %strings
Pre-commit hooks added, including black and flake8
Added CONTRIBUTING.rst
Added github actions to push to PyPi with github tags
0.3.0 - 2020-01-10
Features
Added a SKIP_CLEANUP setting
Improvements
Improved all tests to be more verbose
Improved the README with more information and a list of all the available settings
0.2.3 - 2020-01-09
Improvements
Added tests written in pytests, 100% codecov
Added Django2.2 and Django3 to github workflow as two steps
Improved logging
0.2.2 - 2019-12-21
Improvements
Removed the mandatory DJANGO_GUID settings in settings.py. Added an example project to demonstrate how to set the project up
0.2.1 - 2019-12-21
Improvements
Workflow added, better docstrings, easier to read flow
0.2.0 - 2019-12-21
Features
Header name and header GUID validation can be specified through Django settings
2019-12-20
Initial release
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_guid-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2492c18647854e7d22ee2fd0affe7eeabb17e93efe3adad84f645c6508d93f68 |
|
MD5 | d25d6fd79322ab0b4559b94d85a8b93c |
|
BLAKE2b-256 | 1a75887ad1c666aeb8e8a567af2c1983af03b3374de76f04315b2542a9ca4e54 |