Metadata-Version: 1.1
Name: django-guid
Version: 1.0.0
Summary: Middleware that makes a request GUID available from anywhere and injects it into your logs.
Home-page: https://github.com/JonasKs/django-guid
Author: Jonas Krüger Svensson
Author-email: jonas-ks@hotmail.com
License: BSD
Download-URL: https://pypi.python.org/pypi/django-guid
Description: Django GUID
        ===========
        
        .. image:: https://img.shields.io/pypi/v/django-guid.svg
            :target: https://pypi.python.org/pypi/django-guid
        .. image:: https://img.shields.io/pypi/pyversions/django-guid.svg
            :target: https://pypi.python.org/pypi/django-guid#downloads
        .. image:: https://img.shields.io/pypi/djversions/django-guid.svg
            :target: https://pypi.python.org/pypi/django-guid
        .. image:: https://codecov.io/gh/jonasks/django-guid/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/jonasks/django-guid
        .. image:: https://readthedocs.org/projects/django-guid/badge/?version=latest
            :target: https://django-guid.readthedocs.io/en/latest/?badge=latest
        .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
            :target: https://django-guid.readthedocs.io/en/latest/?badge=latest
        
        
        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:
        
        .. code-block:: bash
        
            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:
        
        .. code-block:: bash
        
            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 <https://django-guid.readthedocs.io/en/latest/extended_example.html>`_.
        
        
        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
        --------
        
        * :code:`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 :code:`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 :code:`django.request` or :code:`django.server`
                logs. If you do not want clean up of GUIDs and know what you're doing, you can enable :code:`SKIP_CLEANUP`.
        
            Default: False
        
        * :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
        
        
        Installation
        ------------
        
        Python package::
        
            pip install django-guid
        
        In your project's :code:`settings.py` add these settings:
        
        (If these settings are confusing, please have a look in the demo project
        `settings.py <https://github.com/JonasKs/django-guid/blob/master/demoproj/settings.py>`_ file for a complete setup.)
        
        
        Add the middleware to the :code:`MIDDLEWARE` setting (To ensure the GUID to be injected in all logs, put it on top):
        
        .. code-block:: python
        
            MIDDLEWARE = [
                'django_guid.middleware.GuidMiddleware',
                ...
             ]
        
        
        Add a filter to your ``LOGGING``:
        
        .. code-block:: python
        
            LOGGING = {
                'filters': {
                    'correlation_id': {
                        '()': 'django_guid.log_filters.CorrelationId'
                    }
                }
            }
        
        
        and put that filter in your handler:
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            LOGGING = {
                'formatters': {
                    'medium': {
                        'format': '%(levelname)s %(asctime)s [%(correlation_id)s] %(name)s %(message)s'
                    }
                }
            }
        
        
        Inspired by `django-log-request-id <https://github.com/dabapps/django-log-request-id>`_ with a
        `django-crequest <https://github.com/Alir3z4/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
        
        
        .. _0.2.0: https://github.com/jonasks/django-guid/compare/0.1.2...0.2.0
        .. _0.2.1: https://github.com/jonasks/django-guid/compare/0.2.0...0.2.1
        .. _0.2.2: https://github.com/jonasks/django-guid/compare/0.2.1...0.2.2
        .. _0.2.3: https://github.com/jonasks/django-guid/compare/0.2.2...0.2.3
        .. _0.3.0: https://github.com/jonasks/django-guid/compare/0.2.3...0.3.0
        .. _0.3.1: https://github.com/jonasks/django-guid/compare/0.3.0...0.3.1
        .. _1.0.0: https://github.com/jonasks/django-guid/compare/0.3.0...1.0.0
        
Keywords: django,logging,request,web,uuid,guid,correlation,correlation-id
Platform: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
