Metadata-Version: 2.1
Name: datapunt-django-audit-log
Version: 0.1.0
Summary: A simple Django app to enable audit logging
Home-page: https://github.com/Amsterdam/auditlog
Author: Datapunt Amsterdam
Author-email: datapunt@amsterdam.nl
License: Mozilla Public License 2.0
Description: 
        For the Python only implementation (which is used by this library) see https://github.com/Amsterdam/python-audit-log
        
        
        # DataPunt Django Audit Log
        
        DataPunt Audit Log is a simple Django app that will log all incoming requests
        and their corresponding responses to a configurable endpoint. 
        
        During the process request phase, the logger is attached to the request. Before 
        returning a response the app can easily provide extra context. In the process
        response phase the audit_log middleware will send the log. 
        
        
        ## Quick start
        
        1. Install using pip
        
            ```bash
            pip install django_audit_log
            ```
           
        2. Add "django_audit_log" to your INSTALLED_APPS:
        
            ```python
            INSTALLED_APPS = [
                ...
                'django_audit_log',
            ]
            ```
        
        3. Add the AuditLogMiddleware to your MIDDLEWARE:
        
            ```python
            MIDDLEWARE = [
                ...
               'django_audit_log.middleware.AuditLogMiddleware',
            ]
            ```
        
        At this point all requests/responses will be logged. For providing extra context
        (which you are strongly urged to do so), see next chapters.
        
        ## Default context info
        
        By default the audit log sends the following json structure per request:
        
        ```json
        {
          "http_request": {
            "method": "get|post|head|options|etc..",
            "url": "https://datapunt.amsterdam.nl?including=querystring",
            "user_agent": "full browser user agent"
          },
          "http_response": {
            "status_code": "http status code",
            "reason": "http status reason",
            "headers": {
              "key": "value"
            }
          },
          "user": {
            "authenticated": "True/False",
            "provider": "auth backend the user authenticated with",
            "realm": "optional realm when using keycloak or another provider",
            "email": "email of logged in user",
            "roles": "roles attached to the logged in user",
            "ip": "ip address"
          }
        }
        ```
            
        Each json entry is set by its corresponding method. In this case, 
        the middleware sets them automatically by calling
        `set_http_request()` and `set_user_fom_request()` 
        in the process_request method. In the process_response method the
        last data is set by invoking `set_http_response()`.
        
        After the response has been processed the middleware automatically
        creates the log item by calling `send_log()`. 
            
        ## Custom optional context info
        
        Per request it is possible to add optional context info. For a complete
        audit log, you are strongly urged to add more info inside your view.
        
        Adding extra context is quite simple. The audit_log object has been added
        to the request by the middleware. Therefore every view can simply access 
        it via the request object.
        
        ### Filter 
        `AuditLog.set_filter(self, object_name, fields, terms)` allows to provide
        info on the requested type of object and the filters that have been used 
        (a user searches for 'terms', which are matched on specific 'fields' of the 
        'object').
        
        This method will add the following details to the log:
        
        ```json
        "filter": {
              "object": "Object name that is requested",
              "fields": "Fields that are being filtered on, if applicable",
              "terms": "Search terms, if applicable"
          }
        ```
        
        ### Results
        `AuditLog.set_results(self, results)` allows to pass a json dict
        detailing exactly what results have been returned to the user. 
        
        It is up to the developer to decide whether the amount of 
        data that would be added here will become a burden instead
        of a blessing.
        
        This method will add the following details to the log:
        
        ```json
        "results": {
            ...
          }
        ```
        
        ### Message and loglevel
        At last, a log message and loglevel can be provided to indicate 
        what the request is actually doing. This is done by calling 
        one of the following methods:
        
        ```python
        AuditLog.debug(self, msg)
        AuditLog.info(self, msg)
        AuditLog.warning(self, msg)
        AuditLog.error(self, msg)
        AuditLog.critical(self, msg)
        ```
            
        These methods will add the following details to the log:
        
        ```json
        "type": "DEBUG|INFO|WARNING|ERROR|etc",
        "message": "log message"
        ```
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: System :: Logging
Description-Content-Type: text/markdown
Provides-Extra: dev
