*************
Configuration
*************

Once django guid has been installed, 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.guid_middleware` to your ``MIDDLEWARE``:

.. code-block:: python

    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 :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',
                # You can optionally override the record field name where the guid is stored
                'correlation_id_field': 'correlation_id'
            }
        }
    }

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/snok/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.


5. Django Management commands (Optional)
----------------------------------------

There is no obvious entry point for Django management commands so GUIDs are not added to code within those commands by default.
If you wish to add GUIDs to logs generated from management commands, you can use a custom base class, such as this example:

.. code-block:: python

    from django.core.management import BaseCommand
    from django_guid.context import guid
    from django_guid.utils import generate_guid


    class CommandWithGUID(BaseCommand):

        def handle(self, *args, **options):
            guid.set(generate_guid())
            self.do_task(*args, **options)

        def do_task(self, *args, **options):
            """
            The actual logic of the command. Subclasses must implement
            this method.
            """
            raise NotImplementedError(
                "subclasses of CommandWithGUID must provide a do_task() method"
            )


You can then inherit from this when creating your own management commands and all logs will have a GUID available.
For example, if you have the class above in a file `command.py` in your `home` app:

.. code-block:: python

    from home.command import CommandWithGUID


    class MyCommandWithGUID(CommandWithGUID):

        def do_task(self, *args, **options):
            """
            Add the code for your custom command here
            """
            do_something()
