Django GUID attaches a unique correlation ID/request ID to all your log outputs for every request.

Overview

Django GUID

Now with ASGI support!

Package version Downloads Django versions ASGI WSGI

Docs Codecov Black Pre-commit


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.

Which version of Django GUID you should use depends on your Django version and whether you run ASGI or WSGI servers. To determine which Django-GUID version you should use, please see the table below.

Django version Django-GUID version
3.1.1 or above 3.x.x - ASGI and WSGI
3.0.0 - 3.1.0 2.x.x - Only WSGI
2.2.x 2.x.x - Only WSGI

Django GUID >= 3.0.0 uses ContextVar to store and access the GUID. Previous versions stored the GUID to an object, making it accessible by using the ID of the current thread. (Version 2 of Django GUID is supported until Django2.2 LTS is over.)


Resources:


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.

Comments
  • Add IGNORE_URLS setting

    Add IGNORE_URLS setting

    This (optional) setting will allow a user to opt-out of the middleware for certain URLs.

    The setting is a list of strings, which are the paths of urls to ignore. The paths can be written with prefix '/' and/or suffix '/', or without them.

    Related to issue #37

    enhancement 
    opened by Iftahh 11
  • Conditionally use deprecated default_app_config

    Conditionally use deprecated default_app_config

    default_app_config is being removed in Django 4.1 and a new warning has shown up since django 3.2

    https://docs.djangoproject.com/en/dev/internals/deprecation/#deprecation-removed-in-4-1

    opened by dustinchilson 10
  • [BUG] - Missing CHANGELOG.rst from packaged tar.gz

    [BUG] - Missing CHANGELOG.rst from packaged tar.gz

    Describe the bug setup.py includes a dependency on CHANGELOG.rst which is not included in the .tar.gz packages

    To Reproduce Retrieve django-guid-.tar.gz and try to run setup.py

    I've tested this on 1.1.1, 2.0.0 2.1.0 & 2.20

    Full stack trace [root@dev-rhel7-acme-python-django2-guid django-guid-2.2.0]# /opt/acme/bin/python3 setup.py install Traceback (most recent call last): File "setup.py", line 7, in with open('CHANGELOG.rst') as changelog_file: FileNotFoundError: [Errno 2] No such file or directory: 'CHANGELOG.rst'

    bug 
    opened by wibbit 9
  • Best way to pass on the correlation-id to child threads?

    Best way to pass on the correlation-id to child threads?

    I am running a django application using gunicorn server, and there are some child threads that will be created by the parent thread. I am getting the guid (contextvar) using get_guid method in the parent thread, passing it as an argument to the child threads, and setting the guid contextvar in the child threads using set_guid method (both of these methods are present in django_guid.api module). Only then the guid is visible in the log messages.

    Is this the best way to pass on the correlation-ids to child threads? Or is there an alternate better way?

    question 
    opened by rdpravin1895 8
  • Sentry integration

    Sentry integration

    I still need to:

    • Bump version
    • Write docs

    but the core logic for this PR is done, and I think it would be good to review that before writing docs, to make sure you agree with the some of the design choices.


    This PR introduces a new package setting, INTEGRATIONS which will be a list of pre-made integrations from the new integrations.py.

    The idea for this PR originally, was only to add some functionality for integrating the correlation ID with Sentry, but I think it might be a good idea to design this feature in a way that opens up for more integrations in the future.

    The second addition is the Sentry logic, which I've packaged in a class so that we can bundle validation logic and execution logic for each integration, and separate it from other code.

    Also made some adjustments to doc-strings and inline comments here and there, but feel free to change them back

    enhancement 
    opened by sondrelg 7
  • ASGI support for later Django versions (works with Django 3.0.x)

    ASGI support for later Django versions (works with Django 3.0.x)

    With ASGI being stable and more async support to Django is coming up, this package eventually have to change it's design to be ASGI compliant.

    • ASGI by protocol can handle multiple requests on one thread. Every time await is used, the control of the loop will be handed back to the event loop, queuing the resumption of the function. The next function will run until it calls on an await, and then the entire thing repeats. This means that a thread will by design be able to handle multiple requests.

    • Most of Django do not support awaitat the moment, so django-guid will work on ASGI today. The way it works right now is that when it gets an ASGI request on the event loop, it dispatches it to a thread pool where each thread again handles one request at the time.

    Essentially this means that in the future, in order to keep this package living we have to find another ID to use. Luckily the Django people has been kind to us and implemented a replacement for us.

    I will look into implementing this ASAP.

    Thanks to knbk on #freenode.

    enhancement in progress 
    opened by JonasKs 6
  • Provide error page views that add the guid to the HTML output

    Provide error page views that add the guid to the HTML output

    I would like an easy way to override the Django error page views so that the request guid is included as part of the HTML. This is useful so that customers can easily send the guid to a support team to get faster help.

    suggestion 
    opened by andrew-cybsafe 5
  • IGNORE_URL setting to opt-out for some URLs

    IGNORE_URL setting to opt-out for some URLs

    I have a few requests that I don't want to see in the logs

    eg. a load balancer sends a "ping" once in a while to see the server is up the logs are spammed with generated new GUID messages:

    django_guid - Header `Correlation-ID` was not found in the incoming request. Generated new GUID: cf306e6e90bc42238f025d8d3fddc8ac
    

    for this request I would prefer to opt out of the middleware - a decorator would work nicely

    @no_guid
    def ping(request):
        return HttpResponse("Ok\n")
    

    Edit: It turns out that to use a decorator for opt-out would require to use the process_view hook, which runs after all the middelwares __call__ methods have been run. If the GUID would only be added at that point, it wouldn't be useful for debugging of other middleware, which is not a good idea. For that reason, instead of a decorator, the plan is to use a "black list" of URLs to ignore. I edited the Issue title to reflect this change.

    suggestion 
    opened by Iftahh 5
  • Bump django from 3.2.10 to 3.2.11

    Bump django from 3.2.10 to 3.2.11

    Bumps django from 3.2.10 to 3.2.11.

    Commits
    • 6e499a2 [3.2.x] Bumped version for 3.2.11 release.
    • 8d2f7cf [3.2.x] Fixed CVE-2021-45452 -- Fixed potential path traversal in storage sub...
    • c7fe895 [3.2.x] Fixed CVE-2021-45116 -- Fixed potential information disclosure in dic...
    • a8b32fe [3.2.x] Fixed CVE-2021-45115 -- Prevented DoS vector in UserAttributeSimilari...
    • b0aa070 [3.2.x] Added stub release notes for 3.2.11, and 2.2.26 releases.
    • ae24223 [3.2.x] Refs #33365, Refs #30530 -- Doc'd re_path() behavior change in Django...
    • ecd2793 [3.2.x] Added CVE-2021-44420 to security archive.
    • 1cea03a [3.2.x] Post-release version bump.
    • See full diff in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 4
  • Update test workflow

    Update test workflow

    Changes

    • Adds django matrix with supported package versions and python 3.9 to the test workflow 🚀
    • Removes unnecessary isort config
    • Updates package metadata to include python 3.9 and django 3.1
    opened by sondrelg 4
  • Pass the GUID of a request to the Celery workers

    Pass the GUID of a request to the Celery workers

    Celery tasks triggered by a request will not have the GUID (Correlation-ID) attached to it. Implement a solution to inject the GUID into the Celery logs.

    For Celery tasks that are not triggered by a request, use the task-id instead as a GUID.

    suggestion 
    opened by JonasKs 4
  • chore: Add example projects

    chore: Add example projects

    I really love the idea of small runnable examples. This sets up the starting point for that by adding

    • examples/sync-views
    • examples/async-views

    My goal here has been to remove anything that isn't relevant to the very narrow functionality the examples are meant to show. The sync-views example now has a regular view and an ignored view, and we might actually go one step further and make a dedicated example out of the ignored view.

    If you agree, we can do something like:

    • examples/async-view
    • examples/sync-view
    • examples/ignore-url
    • examples/celery-integration
    • examples/sentry-integration
    • examples/celery-and-sentry-integration

    For now, I just wanted to open this as a first WIP proof of concept


    Update: Added examples for the 6 things I consider important. We might be missing something though :slightly_smiling_face:

    opened by sondrelg 3
  • v4 planning

    v4 planning

    • [ ] Make ID generator and validator generic, implement transformer (mirror asgi-correlation-id)
    • [ ] Split celery functionality into a separate package
    • [ ] Split sentry functionality into a separate package
    • [ ] Create extras for both
    • [x] Update license
    • [ ] Update test project to handle Django deprecation warnings
    • [x] Update to Poetry v1.2
    • [ ] Update classifiers
    • [ ] Rework docs (drop sphinx and just have readmes per module?)
    • [ ] Remove get_guid and set_guid
    • [ ] Create example projects for each feature

    Essentially we want to de-bloat the core a little, making it possible to install the core middleware without anything else. It's possible to install the middleware today, without adding celery as a dependency, but the celery code is still contained in the wheel.

    There's also some Sentry + Celery logic to consider @JonasKs. Do we put that in its own third package? Something to think about 🤔

    suggestion 
    opened by sondrelg 3
Releases(3.3.0)
  • 3.3.0(May 6, 2022)

    Features

    • Add UUID_FORMAT setting, allowing users to chose UUID/GUID format.
      • hex: 776336d4545e43e1bd3b017794af48e9 (default)
      • string: 776336d4-545e-43e1-bd3b-017794af48e9

    PR #81 by @Mdslino 🥇

    Source code(tar.gz)
    Source code(zip)
  • 3.2.2(Mar 7, 2022)

  • 3.2.1(Dec 13, 2021)

    Fixes:

    • Adjusted package requirements to allow Django >= v4
    • Added log input sanitation in the middleware
    • Added py.typed to enable type checking
    Source code(tar.gz)
    Source code(zip)
  • 2.2.1(Feb 24, 2021)

  • 3.2.0(Dec 3, 2020)

  • 3.1.0(Nov 19, 2020)

    Features

    • Added a new setting, UUID_LENGTH, which lets you crop the UUIDs generated for log filters.
    • Added a new integration for tracing with Celery
    Source code(tar.gz)
    Source code(zip)
  • 3.1.0-rc1(Nov 18, 2020)

    Features

    • Added a new setting, UUID_LENGTH, which lets you crop the UUIDs generated for log filters.
    • Added a new integration for tracing with Celery
    Source code(tar.gz)
    Source code(zip)
  • 3.0.1(Nov 12, 2020)

  • 3.0.0(Oct 28, 2020)

    Brings full async/ASGI (as well as the old WSGI) support to Django GUID using ContextVars instead of thread locals.

    Breaking changes

    This version requires Django>=3.1.1. For previous versions of Django, please use django-guid<3.0.0 (Such as django-guid==2.2.0).

    If you've already implemented django-guid in your project and are currently upgrading to Django>=3.1.1, please see the upgrading docs

    Source code(tar.gz)
    Source code(zip)
  • 2.2.0(Apr 12, 2020)

  • 2.1.0(Mar 11, 2020)

    Features

    • Integration module, which enables the users of django_guid to extend functionality.
    • Added a integration for Sentry, tagging the Sentry issue with the GUID used for the request.

    Other

    • Added docs for integrations
    Source code(tar.gz)
    Source code(zip)
  • 2.0.0(Mar 3, 2020)

    This version contains backwards incompatible changes. Read the entire changelog before upgrading

    Deprecated

    • SKIP_CLEANUP: After a request is finished, the Correlation ID is cleaned up using the request_finished Django signal.

    Incompatible changes

    • django_guid must be in INSTALLED_APPS due to usage of signals.

    Improvements

    • Restructured README and docs.
    Source code(tar.gz)
    Source code(zip)
  • 1.1.1(Feb 12, 2020)

  • 1.1.0(Feb 10, 2020)

    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
    Source code(tar.gz)
    Source code(zip)
  • 1.0.1(Feb 8, 2020)

    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
    Source code(tar.gz)
    Source code(zip)
Owner
snok
Open source collaboration
snok
A beginner django project and also my first Django project which involves shortening of a longer URL into a short one using a unique id.

Django-URL-Shortener A beginner django project and also my first Django project which involves shortening of a longer URL into a short one using a uni

Rohini Rao 3 Aug 8, 2021
Django URL Shortener is a Django app to to include URL Shortening feature in your Django Project

Django URL Shortener Django URL Shortener is a Django app to to include URL Shortening feature in your Django Project Install this package to your Dja

Rishav Sinha 4 Nov 18, 2021
Yet another Django audit log app, hopefully the simplest one.

django-easy-audit Yet another Django audit log app, hopefully the easiest one. This app allows you to keep track of every action taken by your users.

Natán 510 Jan 2, 2023
Log and View requests made on Django

Django Request Viewer Log and view requests made on your Django App Introduction Recently, @ichtrojan and @toniastro released horus, a request logger

Akere Mukhtar 26 May 29, 2022
With Django Hijack, admins can log in and work on behalf of other users without having to know their credentials.

Django Hijack With Django Hijack, admins can log in and work on behalf of other users without having to know their credentials. Docs 3.x docs are avai

null 1.2k Jan 5, 2023
Get inside your stronghold and make all your Django views default login_required

Stronghold Get inside your stronghold and make all your Django views default login_required Stronghold is a very small and easy to use django app that

Mike Grouchy 384 Nov 23, 2022
Django-environ allows you to utilize 12factor inspired environment variables to configure your Django application.

Django-environ django-environ allows you to use Twelve-factor methodology to configure your Django application with environment variables. import envi

Daniele Faraglia 2.7k Jan 7, 2023
Rosetta is a Django application that eases the translation process of your Django projects

Rosetta Rosetta is a Django application that facilitates the translation process of your Django projects. Because it doesn't export any models, Rosett

Marco Bonetti 909 Dec 26, 2022
pytest-django allows you to test your Django project/applications with the pytest testing tool.

pytest-django allows you to test your Django project/applications with the pytest testing tool.

pytest-dev 1.1k Dec 14, 2022
django-dashing is a customisable, modular dashboard application framework for Django to visualize interesting data about your project. Inspired in the dashboard framework Dashing

django-dashing django-dashing is a customisable, modular dashboard application framework for Django to visualize interesting data about your project.

talPor Solutions 703 Dec 22, 2022
Django-Audiofield is a simple app that allows Audio files upload, management and conversion to different audio format (mp3, wav & ogg), which also makes it easy to play audio files into your Django application.

Django-Audiofield Description: Django Audio Management Tools Maintainer: Areski Contributors: list of contributors Django-Audiofield is a simple app t

Areski Belaid 167 Nov 10, 2022
A Django app to initialize Sentry client for your Django applications

Dj_sentry This Django application intialize Sentry SDK to your Django application. How to install You can install this packaging by using: pip install

Gandi 1 Dec 9, 2021
A middleware to log the requests and responses using loguru.

Django Loguru The extension was based on another one and added some extra flavours. One of the biggest problems with the apps is the logging and that

Tiago Silva 9 Oct 11, 2022
DCM is a set of tools that helps you to keep your data in your Django Models consistent.

Django Consistency Model DCM is a set of tools that helps you to keep your data in your Django Models consistent. Motivation You have a lot of legacy

Occipital 59 Dec 21, 2022
Service request portal on top of Ansible Tower

Squest - A service request portal based on Ansible Tower Squest is a Web portal that allow to expose Tower based automation as a service. If you want

Hewlett Packard Enterprise 183 Jan 4, 2023
Django query profiler - one profiler to rule them all. Shows queries, detects N+1 and gives recommendations on how to resolve them

Django Query Profiler This is a query profiler for Django applications, for helping developers answer the question "My Django code/page/API is slow, H

Django Query Profiler 116 Dec 15, 2022
Meta package to combine turbo-django and stimulus-django

Hotwire + Django This repository aims to help you integrate Hotwire with Django ?? Inspiration might be taken from @hotwired/hotwire-rails. We are sti

Hotwire for Django 31 Aug 9, 2022
django-reversion is an extension to the Django web framework that provides version control for model instances.

django-reversion django-reversion is an extension to the Django web framework that provides version control for model instances. Requirements Python 3

Dave Hall 2.8k Jan 2, 2023
Cookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.

Cookiecutter Django Powered by Cookiecutter, Cookiecutter Django is a framework for jumpstarting production-ready Django projects quickly. Documentati

Daniel Feldroy 10k Dec 31, 2022