django-activity-audit 1.3.0.dev20__tar.gz → 1.3.0.dev21__tar.gz

{django_activity_audit-1.3.0.dev20 → django_activity_audit-1.3.0.dev21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-activity-audit
-Version: 1.3.0.dev20
+Version: 1.3.0.dev21
 Summary: A Django package for easy CRUD operation logging and container logs
 Project-URL: Homepage, https://github.com/shree256/django-activity-audit
 Project-URL: Repository, https://github.com/shree256/django-activity-audit
@@ -225,6 +225,7 @@ INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_wit
     "level": "AUDIT",
     "name": "audit.model",
     "message": "CREATE event by User (id: 6f77b814-f9c1-4cab-a737-6677734bc303)",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
     "model": "User",
     "event_type": "CREATE",
     "instance_id": "6f77b814-f9c1-4cab-a737-6677734bc303",
@@ -255,6 +256,7 @@ INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_wit
     "level": "API",
     "name": "audit.request",
     "message": "Audit Internal Request",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
     "service_name": "my_service",
     "request_type": "internal",
     "protocol": "http",
@@ -301,6 +303,7 @@ INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_wit
     "level": "API",
     "name": "audit.request",
     "message": "Audit External Service",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
     "service_name": "apollo",
     "request_type": "external",
     "protocol": "http",

{django_activity_audit-1.3.0.dev20 → django_activity_audit-1.3.0.dev21}/README.md

@@ -183,6 +183,7 @@ INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_wit
     "level": "AUDIT",
     "name": "audit.model",
     "message": "CREATE event by User (id: 6f77b814-f9c1-4cab-a737-6677734bc303)",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
     "model": "User",
     "event_type": "CREATE",
     "instance_id": "6f77b814-f9c1-4cab-a737-6677734bc303",
@@ -213,6 +214,7 @@ INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_wit
     "level": "API",
     "name": "audit.request",
     "message": "Audit Internal Request",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
     "service_name": "my_service",
     "request_type": "internal",
     "protocol": "http",
@@ -259,6 +261,7 @@ INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_wit
     "level": "API",
     "name": "audit.request",
     "message": "Audit External Service",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
     "service_name": "apollo",
     "request_type": "external",
     "protocol": "http",

django_activity_audit-1.3.0.dev21/README.rst

@@ -0,0 +1,341 @@
+Django Activity Audit
+=====================
+
+A Django package that extends the default logging mechanism to track CRUD operations and container logs.
+
+Features
+--------
+
+- Automatic logging of CRUD operations (Create, Read, Update, Delete)
+- Tracks both HTTP requests and model changes
+- Custom log levels Audit(21) and API(22) for CRUD and Request-Response auditing.
+- Structured JSON logs for audit trails
+- Human-readable container logs
+- Separate log files for audit and container logs
+- Console and file output options
+
+Installation
+------------
+
+1. Install the package:
+
+.. code-block:: bash
+
+    pip install django-activity-audit
+
+This also installs `structlog <https://www.structlog.org/>`_ and `orjson <https://github.com/ijl/orjson>`_ as required dependencies.
+
+2. Add ``activity_audit`` to your ``INSTALLED_APPS`` in ``settings.py``:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...
+        'activity_audit',
+    ]
+
+3. Add the middleware to your ``MIDDLEWARE`` in ``settings.py``:
+
+.. code-block:: python
+
+    MIDDLEWARE = [
+        ...
+        'activity_audit.middleware.AuditLoggingMiddleware',
+    ]
+
+4. Configure logging in ``settings.py``.
+
+   Import the formatter helpers from ``activity_audit.config``:
+
+.. code-block:: python
+
+    from activity_audit.config import get_plain_formatter, get_stdlib_formatter
+
+- ``get_stdlib_formatter()`` — structlog JSON renderer. Use in staging/production where logs are ingested by a pipeline (Vector, CloudWatch, etc.).
+- ``get_plain_formatter()`` — structlog plain-text renderer. Use locally for human-readable console output.
+
+**Local development** (plain text output):
+
+.. code-block:: python
+
+    from activity_audit.config import get_plain_formatter, get_stdlib_formatter
+
+    LOGGING = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "structlog": get_stdlib_formatter(),
+            "default":   get_plain_formatter(),
+        },
+        "handlers": {
+            "console":        {"class": "logging.StreamHandler", "formatter": "default"},
+            "console_struct": {"class": "logging.StreamHandler", "formatter": "structlog"},
+        },
+        "root": {
+            "level": "INFO",
+            "handlers": ["console"],   # plain text fallback for all loggers
+        },
+        "loggers": {
+            # Structlog owns these — explicit handler, no propagation to avoid double output
+            "audit.model":   {"handlers": ["console_struct"], "propagate": False},
+            "audit.request": {"handlers": ["console_struct"], "propagate": False},
+            "audit.login":   {"handlers": ["console_struct"], "propagate": False},
+
+            # Celery — structlog formats log_type correctly
+            "celery":        {"level": "INFO", "handlers": ["console_struct"], "propagate": False},
+            "celery.task":   {"level": "INFO", "handlers": ["console_struct"], "propagate": False},
+            "celery.beat":   {"level": "INFO", "handlers": ["console_struct"], "propagate": False},
+
+            # Third-party noise control — WARNING only, routed to root
+            "django.db.backends": {"level": "WARNING", "handlers": [], "propagate": True},
+            "boto3":              {"level": "WARNING", "handlers": [], "propagate": True},
+            "botocore":           {"level": "WARNING", "handlers": [], "propagate": True},
+
+            # Framework loggers
+            "django":        {"level": "INFO", "handlers": [], "propagate": True},
+            "uvicorn":       {"level": "INFO", "handlers": [], "propagate": True},
+            "uvicorn.error": {"level": "INFO", "handlers": [], "propagate": True},
+            "uvicorn.access":{"level": "INFO", "handlers": [], "propagate": True},
+        },
+    }
+
+**Staging / production** (structured JSON output): identical structure, but the ``root`` handler also uses ``console_struct`` (or keep ``console`` for mixed output — both handlers use the same ``StreamHandler`` class):
+
+.. code-block:: python
+
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],
+    }
+
+---
+
+When to add a logger entry
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add an explicit logger entry when you need **any** of the following:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 60 40
+
+   * - Situation
+     - What to set
+   * - Route to structured JSON (``console_struct``)
+     - ``handlers: ["console_struct"], propagate: False``
+   * - Suppress a noisy third-party library
+     - ``level: "WARNING", handlers: [], propagate: True``
+   * - Prevent double output for a structlog-owned logger
+     - ``handlers: ["console_struct"], propagate: False``
+   * - Change the log level for a specific namespace
+     - Set ``level`` explicitly
+
+**Do not** add a logger entry if the default behaviour is acceptable — a logger with no entry propagates to ``root`` and is emitted in plain text at INFO level. That is the correct behaviour for most application loggers.
+
+Silencing audit loggers (route to root instead of structlog)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default ``audit.model``, ``audit.request``, and ``audit.login`` are pointed at ``console_struct`` with ``propagate: False`` so only the structlog-formatted JSON line is emitted.
+
+To stop structlog from handling them and fall back to the plain-text root logger instead, set ``handlers: []`` and ``propagate: True``:
+
+.. code-block:: python
+
+    "loggers": {
+        "audit.model":   {"handlers": [], "propagate": True},
+        "audit.request": {"handlers": [], "propagate": True},
+        "audit.login":   {"handlers": [], "propagate": True},
+    }
+
+This routes all three through the ``root`` logger (``console`` handler, ``default`` / plain-text formatter). Use this when you want to completely disable structured audit output — for example, in a minimal local environment or during debugging.
+
+5. Configure the service name in ``settings.py`` (optional, defaults to ``"default"``):
+
+.. code-block:: python
+
+    AUDIT_SERVICE_NAME = "my_service"
+
+6. For external services logging, extend ``HTTPClient`` or ``SFTPClient``:
+
+.. code-block:: python
+
+    class ExternalService(HTTPClient):
+        def __init__(self):
+            super().__init__("service_name")
+
+        def connect(self):
+            url = "https://www.sample.com"
+            response = self.get(url)  # sample log structure below
+
+8. Create ``audit_logs`` folder in project directory
+
+Log Types
+---------
+
+Container Logs
+~~~~~~~~~~~~~~
+
+Console Log Format::
+
+    '%(levelname)s %(asctime)s %(pathname)s %(module)s %(funcName)s %(message)s'
+    -----------------------------------------------------------------------------
+    INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_with_contacts_and_diseases Patient 'd6c9a056-0b57-453a-8c0f-44319004b761 - Patient3' created.
+
+APP Log
+~~~~~~~
+
+.. code-block:: json
+
+    {
+        "timestamp": "2025-05-15 13:38:02.141",
+        "level": "DEBUG",
+        "name": "botocore.auth",
+        "path": "/opt/venv/lib/python3.11/site-packages/botocore/auth.py",
+        "module": "auth",
+        "function": "add_auth",
+        "message": "Calculating signature using v4 auth.",
+        "exception": ""
+    }
+
+CRUD Log
+~~~~~~~~
+
+.. code-block:: json
+
+    {
+        "timestamp": "2025-08-16 17:06:32.403",
+        "level": "AUDIT",
+        "name": "audit.model",
+        "message": "CREATE event by User (id: 6f77b814-f9c1-4cab-a737-6677734bc303)",
+        "model": "User",
+        "event_type": "CREATE",
+        "instance_id": "6f77b814-f9c1-4cab-a737-6677734bc303",
+        "instance_repr": {
+            "name": "Test Model",
+            "is_active": true,
+            "created_at": "2025-08-29T08:18:54Z",
+            "updated_at": "2025-08-29T08:18:54Z"
+        },
+        "user_id": "cae8ffb4-ba52-409c-9a6f-e10362bfaf97",
+        "user_info": {
+            "title": "mr",
+            "email": "example@source.com",
+            "first_name": "mohamlal",
+            "middle_name": "v",
+            "last_name": "nair",
+            "sex": "m"
+        },
+        "extra": {}
+    }
+
+Request-Response Log
+~~~~~~~~~~~~~~~~~~~~
+
+Incoming Log Format:
+
+.. code-block:: json
+
+    {
+        "timestamp": "2025-05-19 15:25:27.836",
+        "level": "API",
+        "name": "audit.request",
+        "message": "Audit Internal Request",
+        "service_name": "my_service",
+        "request_type": "internal",
+        "protocol": "http",
+        "user_id": "14ab1197-ebdd-4300-a618-5910e0219936",
+        "user_info": {
+            "title": "mr",
+            "email": "example@email.com",
+            "first_name": "mohanlal",
+            "middle_name": "",
+            "last_name": "nair",
+            "sex": "male",
+            "date_of_birth": "21/30/1939"
+        },
+        "request_repr": {
+            "method": "GET",
+            "path": "/api/v1/health/",
+            "query_params": {},
+            "headers": {
+                "Content-Type": "application/json"
+            },
+            "body": {
+                "title": "hello"
+            }
+        },
+        "response_repr": {
+            "headers": {
+                "Content-Type": "application/json"
+            },
+            "body": {
+                "status": "ok"
+            }
+        },
+        "error_message": null,
+        "execution_time": 5.376734018325806
+    }
+
+External Log Format:
+
+.. code-block:: json
+
+    {
+        "timestamp": "2025-05-19 15:25:27.717",
+        "level": "API",
+        "name": "audit.request",
+        "message": "Audit External Service",
+        "service_name": "apollo",
+        "request_type": "external",
+        "protocol": "http",
+        "user_id": "14ab1197-ebdd-4300-a618-5910e0219936",
+        "user_info": {
+            "title": "mr",
+            "email": "example@email.com",
+            "first_name": "mohanlal",
+            "middle_name": "",
+            "last_name": "nair",
+            "sex": "male",
+            "date_of_birth": "21/30/1939"
+        },
+        "request_repr": {
+            "endpoint": "example.com",
+            "method": "GET",
+            "headers": {},
+            "body": {}
+        },
+        "response_repr": {
+            "status_code": 200,
+            "body": {
+                "title": "title",
+                "expiresIn": 3600,
+                "error": "",
+                "errorDescription": ""
+            }
+        },
+        "error_message": "",
+        "execution_time": 5.16809344291687
+    }
+
+Notes
+-----
+
+- Compatible with **Django 4.2+** and **Python 3.8+**.
+- Designed for easy integration with observability stacks using Vector, ClickHouse, and Grafana.
+- Capture Django CRUD operations automatically
+- Write structured JSON logs
+- Ready for production-grade logging pipelines
+- Simple pip install, reusable across projects
+- Zero additional database overhead!
+
+Related Tools
+-------------
+
+- `Vector.dev <https://vector.dev/>`_
+- `ClickHouse <https://clickhouse.com/>`_
+- `Grafana <https://grafana.com/>`_
+
+License
+-------
+
+This project is licensed under the MIT License - see the LICENSE file for details.

{django_activity_audit-1.3.0.dev20 → django_activity_audit-1.3.0.dev21}/activity_audit/formatters.py

@@ -63,10 +63,13 @@ class AppFormatter(logging.Formatter):
             "log_type": self.log_type,
         }
 
-        # Add exception info if present for ERROR
         if record.exc_info:
             log_data["exception"] = "{}".format(self.formatException(record.exc_info))
 
+        extra = getattr(record, "extra", "")
+        if extra:
+            log_data["extra"] = extra
+
         return json.dumps(log_data, default=_json_default)
 
 
@@ -106,6 +109,7 @@ class APIFormatter(logging.Formatter):
             "response_repr",
             "error_message",
             "execution_time",
+            "extra",
         ]
 
         for field in audit_fields:

{django_activity_audit-1.3.0.dev20 → django_activity_audit-1.3.0.dev21}/activity_audit/middleware.py

@@ -118,6 +118,18 @@ class AuditLoggingMiddleware(MiddlewareMixin):
     }
     """
 
+    def _init_log_data(self):
+        return {
+            "service_name": SERVICE_NAME,
+            "request_type": REQUEST_TYPES[0],
+            "protocol": None,
+            "request_repr": {},
+            "response_repr": {},
+            "error_message": None,
+            "execution_time": 0,
+            "extra": {},
+        }
+
     def __init__(self, get_response):
         self.get_response = get_response
 
@@ -135,15 +147,7 @@ class AuditLoggingMiddleware(MiddlewareMixin):
         if not should_log_url(request.path):
             return self.get_response(request)
 
-        log_data = {
-            "service_name": SERVICE_NAME,
-            "request_type": REQUEST_TYPES[0],
-            "protocol": None,
-            "request_repr": {},
-            "response_repr": {},
-            "error_message": None,
-            "execution_time": 0,
-        }
+        log_data = self._init_log_data()
         start_time = time.time()
 
         # Log request
@@ -209,15 +213,7 @@ class AuditLoggingMiddleware(MiddlewareMixin):
         if not should_log_url(request.path):
             return await self.get_response(request)
 
-        log_data = {
-            "service_name": SERVICE_NAME,
-            "request_type": REQUEST_TYPES[0],
-            "protocol": None,
-            "request_repr": {},
-            "response_repr": {},
-            "error_message": None,
-            "execution_time": 0,
-        }
+        log_data = self._init_log_data()
         start_time = time.time()
 
         # Log request

{django_activity_audit-1.3.0.dev20 → django_activity_audit-1.3.0.dev21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-activity-audit"
-version = "1.3.0.dev20"
+version = "1.3.0.dev21"
 description = "A Django package for easy CRUD operation logging and container logs"
 authors = [
     { name = "Shreeshan", email = "shreeshan256@gmail.com" }

django_activity_audit-1.3.0.dev20/README.rst

@@ -1,263 +0,0 @@
-Django Activity Audit
-=====================
-
-A Django package that extends the default logging mechanism to track CRUD operations and container logs.
-
-Features
---------
-
-- Automatic logging of CRUD operations (Create, Read, Update, Delete)
-- Tracks both HTTP requests and model changes
-- Custom log levels Audit(21) and API(22) for CRUD and Request-Response auditing.
-- Structured JSON logs for audit trails
-- Human-readable container logs
-- Separate log files for audit and container logs
-- Console and file output options
-
-Installation
-------------
-
-1. Install the package::
-
-    pip install django-activity-audit
-
-2. Add ``activity_audit`` to your ``INSTALLED_APPS`` in ``settings.py``::
-
-    INSTALLED_APPS = [
-        ...
-        'activity_audit',
-    ]
-
-3. Add the middleware to your ``MIDDLEWARE`` in ``settings.py``::
-
-    MIDDLEWARE = [
-        ...
-        'activity_audit.middleware.AuditLoggingMiddleware',
-    ]
-
-4. Configure logging in ``settings.py``::
-
-    from activity_audit import *
-
-    LOGGING = {
-        "version": 1,
-        "disable_existing_loggers": False,
-        "formatters": {
-            "json": get_json_formatter(),
-            "verbose": get_console_formatter(),
-        },
-        "handlers": {
-            "console": {
-                "level": "DEBUG",
-                "class": "logging.StreamHandler",
-                "formatter": "verbose",
-            },
-            "file": get_json_handler(level="DEBUG", formatter="json"),
-            "api_file": get_api_file_handler(),
-            "audit_file": get_audit_handler(),
-        },
-        "root": {"level": "DEBUG", "handlers": ["console", "file"]},
-        "loggers": {
-            "audit.request": {
-                "handlers": ["api_file"],
-                "level": "API",
-                "propagate": False,
-            },
-            "audit.model": {
-                "handlers": ["audit_file"],
-                "level": "AUDIT",
-                "propagate": False,
-            },
-            "django": {
-                "handlers": ["console", "file"],
-                "level": "INFO",
-                "propagate": False,
-            },
-        }
-    }
-
-5. Configure the service name in ``settings.py`` (optional, defaults to ``"default"``)::
-
-    AUDIT_SERVICE_NAME = "my_service"
-
-6. For external services logging, extend ``HTTPClient`` or ``SFTPClient``::
-
-    class ExternalService(HTTPClient):
-        def __init__(self):
-            super().__init__("service_name")
-
-        def connect(self):
-            url = "https://www.sample.com"
-            response = self.get(url) # sample log structure below
-
-7. Create ``audit_logs`` folder in project directory
-
-Log Types
----------
-
-Container Logs
---------------
-
-Console Log Format::
-
-    '%(levelname)s %(asctime)s %(pathname)s %(module)s %(funcName)s %(message)s'
-    -----------------------------------------------------------------------------
-    INFO 2025-04-30 08:51:10,403 /app/patients/api/utils.py utils create_patient_with_contacts_and_diseases Patient 'd6c9a056-0b57-453a-8c0f-44319004b761 - Patient3' created.
-
-APP Log 
--------
-
-::
-
-    {
-        "timestamp": "2025-05-15 13:38:02.141",
-        "level": "DEBUG",
-        "name": "botocore.auth",
-        "path": "/opt/venv/lib/python3.11/site-packages/botocore/auth.py",
-        "module": "auth",
-        "function": "add_auth",
-        "message": "Calculating signature using v4 auth.",
-        "exception": ""
-    }
-
-CRUD Log
---------
-
-::
-
-    {
-        "timestamp": "2025-08-16 17:06:32.403",
-        "level": "AUDIT",
-        "name": "audit.model",
-        "message": "CREATE event by User (id: 6f77b814-f9c1-4cab-a737-6677734bc303)",
-        "model": "User",
-        "event_type": "CREATE",
-        "instance_id": "6f77b814-f9c1-4cab-a737-6677734bc303",
-        "instance_repr" : {
-            "name": "Test Model",
-            "is_active": true,
-            "created_at": "2025-08-29T08:18:54Z",
-            "updated_at": "2025-08-29T08:18:54Z"
-        },
-        "user_id": "14ab1197-ebdd-4300-a618-5910e0219936",
-        "user_info": {
-            "title": "mr",
-            "email": "example@email.com",
-            "first_name": "mohanlal",
-            "middle_name": "",
-            "last_name": "nair",
-            "sex": "male",
-            "date_of_birth": "21/30/1939"
-        },
-        "extra": {}
-    }
-
-Request-Response Log
---------------------
-
-Incoming Log Format::
-
-    {
-        "timestamp": "2025-05-19 15:25:27.836",
-        "level": "API",
-        "name": "audit.request",
-        "message": "Audit Internal Request",
-        "service_name": "my_service",
-        "request_type": "internal",
-        "protocol": "http",
-        "user_id": "14ab1197-ebdd-4300-a618-5910e0219936",
-        "user_info": {
-            "title": "mr",
-            "email": "example@email.com",
-            "first_name": "mohanlal",
-            "middle_name": "",
-            "last_name": "nair",
-            "sex": "male",
-            "date_of_birth": "21/30/1939"
-        },
-        "request_repr": {
-            "method": "GET",
-            "path": "/api/v1/health/",
-            "query_params": {},
-            "headers": {
-                "Content-Type": "application/json",
-            },
-            "user": null,
-            "body": {
-                "title": "hello"
-            }
-        },
-        "response_repr": {
-            "status_code": 200,
-            "headers": {
-                "Content-Type": "application/json",
-            },
-            "body": {
-                "status": "ok"
-            }
-        },
-        "error_message": null,
-        "execution_time": 5.376734018325806
-    }
-
-External Log format::
-
-    {
-        "timestamp": "2025-05-19 15:25:27.717",
-        "level": "API",
-        "name": "audit.request",
-        "message": "Audit External Service",
-        "service_name": "apollo",
-        "request_type": "external",
-        "protocol": "http",
-        "user_id": "14ab1197-ebdd-4300-a618-5910e0219936",
-        "user_info": {
-            "title": "mr",
-            "email": "example@email.com",
-            "first_name": "mohanlal",
-            "middle_name": "",
-            "last_name": "nair",
-            "sex": "male",
-            "date_of_birth": "21/30/1939"
-        },
-        "request_repr": {
-            "endpoint": "example.com",
-            "method": "GET",
-            "headers": {},
-            "body": {}
-        },
-        "response_repr": {
-            "status_code": 200,
-            "body": {
-                "title": "title",
-                "expiresIn": 3600,
-                "error": "",
-                "errorDescription": ""
-            }
-        },
-        "error_message": "",
-        "execution_time": 5.16809344291687
-    }
-
-Notes
------
-
-- Compatible with **Django 3.2+** and **Python 3.7+**.
-- Designed for easy integration with observability stacks using Vector, ClickHouse, and Grafana.
-- Capture Django CRUD operations automatically
-- Write structured JSON logs
-- Ready for production-grade logging pipelines
-- Simple pip install, reusable across projects
-- Zero additional database overhead!
-
-Related Tools
--------------
-
-- `Vector.dev <https://vector.dev/>`_
-- `ClickHouse <https://clickhouse.com/>`_
-- `Grafana <https://grafana.com/>`_
-
-License
--------
-
-This project is licensed under the MIT License - see the LICENSE file for details.