Metadata-Version: 1.1
Name: django-guid
Version: 2.1.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://readthedocs.org/projects/django-guid/badge/?version=latest
            :target: https://django-guid.readthedocs.io/en/latest/?badge=latest
        .. image:: https://codecov.io/gh/jonasks/django-guid/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/jonasks/django-guid
        .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
            :target: https://django-guid.readthedocs.io/en/latest/?badge=latest
        .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
            :target: https://github.com/pre-commit/pre-commit
        
        
        Django GUID attaches a unique correlation ID to all your log outputs for every requests you handle. In other words, every error, and really every log now has an ID connecting it to all other relevant logs, making
        debugging simple.
        
        The package stores a GUID to an object, making it accessible by using the ID of the current thread. This makes integrations possible, as the ID can be returned as a header (built in setting) or forwarded manually to other systems (built in API), making it possible to extend the reach of correlation IDs to whole systems.
        
        **Resources**:
        
        * Free software: BSD License
        * Documentation: https://django-guid.readthedocs.io
        * Homepage: https://github.com/JonasKs/django-guid
        
        **Examples**
        
        Log output with a GUID:
        
        .. code-block::
        
            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::
        
            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 <https://django-guid.readthedocs.io>`_ 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 = [],
            }
        
        
        
        **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: []
        
        *************
        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.GuidMiddleware` to your ``MIDDLEWARE``:
        
        .. code-block:: python
        
            MIDDLEWARE = [
                'django_guid.middleware.GuidMiddleware',
                ...
             ]
        
        
        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 <https://github.com/JonasKs/django-guid/blob/master/demoproj/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.
        
        
        Changelog
        =========
        
        `2.1.0`_ - 2020-11-03
        ---------------------
        **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
        
        
        `2.0.0`_ - 2020-03-02
        ---------------------
        **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.
        
        
        `1.1.1`_ - 2020-02-12
        ---------------------
        
        **Improvements**
        
        * Fixed ``EXPOSE_HEADER`` documentation issue. New release has to be pushed to fix PyPi docs.
        
        
        `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
        
        
        .. _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
        .. _1.0.1: https://github.com/jonasks/django-guid/compare/1.0.0...1.0.1
        .. _1.1.0: https://github.com/jonasks/django-guid/compare/1.0.1...1.1.0
        .. _1.1.1: https://github.com/jonasks/django-guid/compare/1.1.0...1.1.1
        .. _2.0.0: https://github.com/jonasks/django-guid/compare/1.1.1...2.0.0
        .. _2.1.0: https://github.com/jonasks/django-guid/compare/2.0.0...2.1.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
