Skip to main content

Middleware that makes a request GUID available from anywhere and injects it into your logs.

Project description

Django GUID

https://img.shields.io/pypi/v/django-guid.svg https://img.shields.io/pypi/pyversions/django-guid.svg https://img.shields.io/pypi/djversions/django-guid.svg https://codecov.io/gh/jonasks/django-guid/branch/master/graph/badge.svg https://readthedocs.org/projects/django-guid/badge/?version=latest https://img.shields.io/badge/code%20style-black-000000.svg

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.

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 as django.request or django.server logs. If you do not want clean up of GUIDs and know what you’re doing, you can enable SKIP_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

Installation

Python package:

pip install django-guid

In your project’s settings.py add these settings:

(If these settings are confusing, please have a look in the demo project settings.py file for a complete setup.)

Add the middleware to the MIDDLEWARE setting (To ensure the GUID to be injected in all 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'
        }
    }
}

and put that filter in your handler:

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

and 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'
        }
    }
}

Inspired by django-log-request-id with a django-crequest approach.

Changelog

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-guid, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size django_guid-1.0.0-py3-none-any.whl (14.2 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size django-guid-1.0.0.tar.gz (13.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page