django-activity-audit 1.3.0.dev18__tar.gz → 1.3.0.dev19__tar.gz

django_activity_audit-1.3.0.dev19/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/python -m pip install \"structlog>=24.0\")"
+    ]
+  }
+}

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-activity-audit
-Version: 1.3.0.dev18
+Version: 1.3.0.dev19
 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
@@ -30,12 +30,15 @@ Provides-Extra: dev
 Requires-Dist: pre-commit>=3.5; (python_version >= '3.9') and extra == 'dev'
 Requires-Dist: pre-commit~=3.5; (python_version < '3.9') and extra == 'dev'
 Requires-Dist: ruff>=0.1.11; extra == 'dev'
+Provides-Extra: structlog
+Requires-Dist: structlog>=24.0; extra == 'structlog'
 Provides-Extra: test
 Requires-Dist: djangorestframework>=3.14.0; extra == 'test'
 Requires-Dist: factory-boy>=3.2.0; extra == 'test'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
 Requires-Dist: pytest-django>=4.0.0; extra == 'test'
 Requires-Dist: pytest>=6.0.0; extra == 'test'
+Requires-Dist: structlog>=24.0; extra == 'test'
 Description-Content-Type: text/markdown
 
 # Django Activity Audit

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/activity_audit/__init__.py

@@ -16,6 +16,8 @@ from activity_audit.utils import (
     get_login_handler,
 )
 
+from .config import get_logger
+
 from . import logger_levels
 
 __all__ = [
@@ -32,4 +34,5 @@ __all__ = [
     "get_async_api_handler",
     "get_async_audit_handler",
     "get_async_login_handler",
+    "get_logger",
 ]

django_activity_audit-1.3.0.dev19/activity_audit/apps.py

@@ -0,0 +1,17 @@
+from django.apps import AppConfig
+
+
+class AuditLoggingConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "activity_audit"
+    verbose_name = "Django Activity Audit"
+
+    def ready(self):
+        from . import (
+            logger_levels,
+            signals,  # noqa
+            unregistered,  # noqa
+        )
+        from .config import configure
+
+        configure()

django_activity_audit-1.3.0.dev19/activity_audit/config.py

@@ -0,0 +1,66 @@
+import structlog
+
+from activity_audit.shared_processors import (
+    _json_default,
+    _orjson_dumps,
+    shared_processors,
+)
+
+
+class AuditBoundLogger(structlog.stdlib.BoundLogger):
+    """Extends structlog BoundLogger with AUDIT, API, and LOGIN log levels."""
+
+    def audit(self, event=None, *args, **kw):
+        return self._proxy_to_logger("audit", event, *args, **kw)
+
+    def api(self, event=None, *args, **kw):
+        return self._proxy_to_logger("api", event, *args, **kw)
+
+    def login(self, event=None, *args, **kw):
+        return self._proxy_to_logger("login", event, *args, **kw)
+
+
+def get_stdlib_formatter() -> dict:
+    """
+    LOGGING formatter dict that routes stdlib loggers through the structlog
+    processor chain. Use for any logger that isn't a native structlog logger
+    (e.g. celery, django, uvicorn).
+    """
+    return {
+        "()": structlog.stdlib.ProcessorFormatter,
+        "processors": [
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            structlog.processors.JSONRenderer(
+                serializer=_orjson_dumps, default=_json_default
+            ),
+        ],
+        "foreign_pre_chain": shared_processors,
+    }
+
+
+def configure() -> None:
+    """
+    Configure structlog for console-only JSON output.
+
+    Produces the same JSON structure as the existing AuditFormatter /
+    APIFormatter / LoginFormatter — same field names, same timestamp format,
+    same uppercase level names — but outputs to stdout via StreamHandler.
+    No file handlers are used.
+
+    merge_contextvars is wired in so Phase 2 (replacing thread-locals with
+    structlog contextvars in middleware) only requires middleware changes;
+    this function and signals.py do not need to change again.
+    """
+    structlog.configure(
+        processors=shared_processors
+        + [
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=AuditBoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> AuditBoundLogger:
+    return structlog.get_logger(name)

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/activity_audit/formatters.py

@@ -4,8 +4,9 @@ import json
 import logging
 import uuid
 
+import structlog.contextvars as ctx
+
 from .constants import LogType
-from .middleware import get_request_id
 
 
 def _json_default(obj):
@@ -55,7 +56,8 @@ class AppFormatter(logging.Formatter):
             "path": record.pathname,
             "module": record.module,
             "function": record.funcName,
-            "request_id": getattr(record, "request_id", None) or get_request_id() or "",
+            "request_id": getattr(record, "request_id", None)
+            or ctx.get_contextvars().get("request_id", ""),
             "message": record.getMessage(),
             "exception": "",
             "log_type": self.log_type,

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/activity_audit/handlers.py

@@ -3,8 +3,14 @@ import queue
 
 from logging.handlers import QueueHandler, QueueListener, RotatingFileHandler
 
-from .formatters import APIFormatter, AppFormatter, AuditFormatter, LoginFormatter
-from .middleware import get_request_id
+import structlog.contextvars as ctx
+
+from .formatters import (
+    APIFormatter,
+    AppFormatter,
+    AuditFormatter,
+    LoginFormatter,
+)
 
 
 class BaseAuditHandler(RotatingFileHandler):
@@ -110,10 +116,10 @@ class AsyncBaseAuditHandler(QueueHandler):
         self._listener.start()
 
     def prepare(self, record):
-        # Capture request_id in the calling thread before the record is queued,
-        # since thread-locals are not accessible from the QueueListener thread.
+        # Snapshot request_id from contextvars before the record is queued —
+        # the QueueListener thread runs in a different context.
         record = super().prepare(record)
-        record.request_id = get_request_id() or ""
+        record.request_id = ctx.get_contextvars().get("request_id", "")
         return record
 
     def close(self):
@@ -170,10 +176,10 @@ class AsyncJsonHandler(QueueHandler):
         self._listener.start()
 
     def prepare(self, record):
-        # Capture request_id in the calling thread before the record is queued,
-        # since thread-locals are not accessible from the QueueListener thread.
+        # Snapshot request_id from contextvars before the record is queued —
+        # the QueueListener thread runs in a different context.
         record = super().prepare(record)
-        record.request_id = get_request_id() or ""
+        record.request_id = ctx.get_contextvars().get("request_id", "")
         return record
 
     def close(self):

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/activity_audit/middleware.py

@@ -1,19 +1,25 @@
 import contextlib
 import json
-import logging
 import re
 import time
 import uuid
 
+import structlog.contextvars as ctx
+
 from asgiref.local import Local
-from asgiref.sync import iscoroutinefunction, markcoroutinefunction, sync_to_async
+from asgiref.sync import (
+    iscoroutinefunction,
+    markcoroutinefunction,
+    sync_to_async,
+)
 from django.http import HttpResponse
 from django.utils.deprecation import MiddlewareMixin
 
+from .config import get_logger
 from .constants import REQUEST_TYPES
 from .settings import REGISTERED_URLS, SERVICE_NAME, UNREGISTERED_URLS
 
-logger = logging.getLogger("audit.request")
+_log = get_logger("audit.request")
 
 _thread_locals = Local()
 
@@ -33,14 +39,6 @@ def set_current_request(request):
     _thread_locals.request = request
 
 
-def get_request_id():
-    return getattr(_thread_locals, "request_id", None)
-
-
-def set_request_id(request_id):
-    _thread_locals.request_id = request_id
-
-
 def get_current_user():
     request = get_current_request()
     if request:
@@ -77,8 +75,6 @@ def get_user_details():
 def clear_request():
     with contextlib.suppress(AttributeError):
         del _thread_locals.request
-    with contextlib.suppress(AttributeError):
-        del _thread_locals.request_id
 
 
 def should_log_url(url):
@@ -135,7 +131,8 @@ class AuditLoggingMiddleware(MiddlewareMixin):
             return self.__acall__(request)
         set_current_request(request)
         request_id = str(uuid.uuid4())
-        set_request_id(request_id)
+        ctx.clear_contextvars()
+        ctx.bind_contextvars(request_id=request_id)
 
         if not should_log_url(request.path):
             return self.get_response(request)
@@ -144,9 +141,6 @@ class AuditLoggingMiddleware(MiddlewareMixin):
             "service_name": SERVICE_NAME,
             "request_type": REQUEST_TYPES[0],
             "protocol": None,
-            "request_id": "",
-            "user_id": "",
-            "user_info": {},
             "request_repr": {},
             "response_repr": {},
             "error_message": None,
@@ -175,8 +169,7 @@ class AuditLoggingMiddleware(MiddlewareMixin):
 
         # Capture user details AFTER authentication has happened
         user_id, user_info = get_user_details()
-        log_data["user_id"] = user_id
-        log_data["user_info"] = user_info
+        ctx.bind_contextvars(user_id=user_id, user_info=user_info)
 
         # TODO: Find way to add status code to response_data
 
@@ -198,20 +191,22 @@ class AuditLoggingMiddleware(MiddlewareMixin):
 
         log_data["execution_time"] = end_time - start_time
         log_data["protocol"] = "https" if request.is_secure() else "http"
-        log_data["request_id"] = request_id
         log_data["request_repr"] = request_data
         log_data["response_repr"] = response_data
 
-        logger.api("Audit Internal Request", extra=log_data)
+        bound = _log.bind(**log_data)
+        bound.api("Audit Internal Request")
 
         clear_request()
+        ctx.clear_contextvars()
 
         return response
 
     async def __acall__(self, request):
         set_current_request(request)
         request_id = str(uuid.uuid4())
-        set_request_id(request_id)
+        ctx.clear_contextvars()
+        ctx.bind_contextvars(request_id=request_id)
 
         if not should_log_url(request.path):
             return await self.get_response(request)
@@ -220,9 +215,6 @@ class AuditLoggingMiddleware(MiddlewareMixin):
             "service_name": SERVICE_NAME,
             "request_type": REQUEST_TYPES[0],
             "protocol": None,
-            "request_id": "",
-            "user_id": "",
-            "user_info": {},
             "request_repr": {},
             "response_repr": {},
             "error_message": None,
@@ -253,8 +245,7 @@ class AuditLoggingMiddleware(MiddlewareMixin):
         user_id, user_info = await sync_to_async(
             get_user_details, thread_sensitive=True
         )()
-        log_data["user_id"] = user_id
-        log_data["user_info"] = user_info
+        ctx.bind_contextvars(user_id=user_id, user_info=user_info)
 
         # TODO: Find way to add status code to response_data
 
@@ -276,12 +267,13 @@ class AuditLoggingMiddleware(MiddlewareMixin):
 
         log_data["execution_time"] = end_time - start_time
         log_data["protocol"] = "https" if request.is_secure() else "http"
-        log_data["request_id"] = request_id
         log_data["request_repr"] = request_data
         log_data["response_repr"] = response_data
 
-        logger.api("Audit Internal Request", extra=log_data)
+        bound = _log.bind(**log_data)
+        bound.api("Audit Internal Request")
 
         clear_request()
+        ctx.clear_contextvars()
 
         return response

django_activity_audit-1.3.0.dev19/activity_audit/shared_processors.py

@@ -0,0 +1,128 @@
+import datetime
+import decimal
+import sys
+
+import orjson
+import structlog
+
+from structlog.processors import CallsiteParameter
+
+from activity_audit.constants import LogType
+
+
+def _orjson_dumps(*args, **kwargs):
+    return orjson.dumps(*args, **kwargs).decode()
+
+
+def _json_default(obj):
+    if isinstance(obj, decimal.Decimal):
+        return float(obj)
+    if isinstance(obj, set):
+        return list(obj)
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="replace")
+    return str(obj)
+
+
+def _audit_timestamp(logger, method, event_dict):
+    """Timestamp in the same format as the existing formatters: 'YYYY-MM-DD HH:MM:SS.mmm'."""
+    event_dict["timestamp"] = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[
+        :-3
+    ]
+    return event_dict
+
+
+def _uppercase_level(logger, method, event_dict):
+    """Uppercase level name to match AUDIT / API / LOGIN convention."""
+    if "level" in event_dict:
+        event_dict["level"] = event_dict["level"].upper()
+    return event_dict
+
+
+def _rename_structlog_keys(logger, method, event_dict):
+    """
+    Rename structlog default keys to match the existing JSON field names:
+      event  → message
+      logger → name
+    """
+    if "event" in event_dict:
+        event_dict["message"] = event_dict.pop("event")
+    if "logger" in event_dict:
+        event_dict["name"] = event_dict.pop("logger")
+    return event_dict
+
+
+def _detect_process_log_type() -> str:
+    argv = " ".join(sys.argv)
+    if "beat" in argv:
+        return LogType.CELERYBEAT
+    if "worker" in argv or "celery" in argv:
+        return LogType.CELERYWORKER
+    return LogType.AUDIT
+
+
+_PROCESS_LOG_TYPE = _detect_process_log_type()
+
+_LOG_TYPE_MAP = {
+    "audit.model": _PROCESS_LOG_TYPE,
+    "audit.request": LogType.API,
+    "audit.login": LogType.LOGIN,
+}
+
+
+def _add_log_type(logger, method, event_dict):
+    """Add log_type based on logger name; all celery.* loggers get the process type."""
+    name = event_dict.get("name", "")
+    if name in _LOG_TYPE_MAP:
+        event_dict["log_type"] = _LOG_TYPE_MAP[name]
+    elif name.startswith("celery"):
+        event_dict["log_type"] = _PROCESS_LOG_TYPE
+    else:
+        event_dict["log_type"] = LogType.APP
+    return event_dict
+
+
+_STANDARD_KEYS = frozenset(
+    {
+        "timestamp",
+        "level",
+        "name",
+        "message",
+        "log_type",
+        "filename",
+        "func_name",
+        "stack_info",
+        "exception",
+        "request_id",
+        "_record",
+        "_from_structlog",
+    }
+)
+
+
+def _collect_extra(logger, method, event_dict):
+    """Move all caller-supplied kwargs that aren't standard fields into 'extra'."""
+    extra = {k: event_dict.pop(k) for k in list(event_dict) if k not in _STANDARD_KEYS}
+    if extra:
+        event_dict["extra"] = extra
+    return event_dict
+
+
+shared_processors = [
+    structlog.contextvars.merge_contextvars,
+    structlog.stdlib.add_log_level,
+    structlog.stdlib.add_logger_name,
+    _audit_timestamp,
+    _uppercase_level,
+    _rename_structlog_keys,
+    _add_log_type,
+    structlog.processors.CallsiteParameterAdder(
+        [
+            CallsiteParameter.FILENAME,
+            CallsiteParameter.FUNC_NAME,
+        ]
+    ),
+    structlog.processors.StackInfoRenderer(),
+    structlog.processors.ExceptionRenderer(),
+    _collect_extra,
+]

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/activity_audit/signals.py

@@ -1,9 +1,10 @@
 import inspect
-import logging
 
 from functools import wraps
 from typing import Any, List
 
+import structlog.contextvars as ctx
+
 from django.apps import apps
 from django.db import models, transaction
 from django.db.models.signals import (
@@ -15,10 +16,10 @@ from django.db.models.signals import (
 from django.dispatch import receiver
 from django.forms.models import model_to_dict
 
-from activity_audit.middleware import get_request_id, get_user_details
+from activity_audit.config import get_logger
 from activity_audit.unregistered import UNREGISTERED_CLASSES
 
-logger = logging.getLogger("audit.model")
+_log = get_logger("audit.model")
 
 EVENT_TYPES = [
     "CREATE",
@@ -129,27 +130,29 @@ def push_log(
     extra: dict = {},
 ) -> None:
     try:
-        user_id, user_info = get_user_details()
-        payload: dict = {
-            "model": model,
-            "instance_id": str(instance_id),
-            "event_type": event_type,
-            "request_id": get_request_id() or "",
-            "user_id": user_id,
-            "user_info": user_info,
-            "instance_repr": instance_repr,
-            "extra": extra,
-        }
+        # Snapshot contextvars now — on_commit fires after the transaction commits
+        # and the middleware may have already cleared contextvars by then.
+        ctx_vars = ctx.get_contextvars()
+        bound = _log.bind(
+            model=model,
+            instance_id=str(instance_id),
+            event_type=event_type,
+            request_id=ctx_vars.get("request_id", ""),
+            user_id=ctx_vars.get("user_id", ""),
+            user_info=ctx_vars.get("user_info", {}),
+            instance_repr=instance_repr,
+            extra=extra,
+        )
 
         def safe_audit_log():
             try:
-                logger.audit(message, extra=payload)
+                bound.audit(message)
             except Exception as e:
-                logger.error(f"Failed to write audit log: {e}")
+                _log.error("Failed to write audit log", error=str(e))
 
         transaction.on_commit(safe_audit_log)
     except Exception as e:
-        logger.error(f"Failed to prepare audit log: {e}")
+        _log.error("Failed to prepare audit log", error=str(e))
 
 
 def instance_to_dict(instance: models.Model) -> dict:

django_activity_audit-1.3.0.dev19/docs/hipaa-audit-gaps.md

@@ -0,0 +1,133 @@
+# HIPAA Audit Gap Analysis
+
+Architecture: Django → stdout → Docker logs → Vector → ClickHouse (self-hosted, in-VPC) → Grafana
+
+---
+
+## Critical — Must Fix
+
+### 1. Sentry Integration Shipping PHI Outside VPC — §164.314
+
+`settings.py` maps AUDIT/API log levels to Sentry. If Sentry is active in production, full request/response payloads and model reprs containing patient data are leaving the VPC to a third-party with no BAA coverage.
+
+**Fix:** Disable Sentry for `audit.*` loggers in production, or strip PHI fields before they reach the Sentry handler.
+
+---
+
+### 2. Response Status Code Missing from API Logs — §164.312(b)
+
+`middleware.py:181` has a `# TODO` for status code. HIPAA requires distinguishing authorized access (200) from denied access (403/401) to identify unauthorized access attempts.
+
+**Fix:** `response.status_code` is directly available on the Django `HttpResponse` object — add it to `response_repr`.
+
+---
+
+### 3. Log Integrity / Tamper-Evidence — §164.312(c)(1)
+
+Audit logs must be protected from unauthorized alteration.
+
+**Fix:**
+- ClickHouse ingest user must have `INSERT` only — no `ALTER`/`DELETE`/`TRUNCATE`
+- Docker daemon socket access restricted to the Vector service account only
+- Separate admin-only ClickHouse role for schema changes
+
+---
+
+### 4. Log Retention Not Enforced — §164.530(j)
+
+HIPAA requires audit log retention for 6 years (2190 days). `backupCount` on local file handlers is irrelevant with Docker log streaming, but ClickHouse TTL and Vector buffering are not configured.
+
+**Fix:**
+- Set ClickHouse TTL policy to 6+ years explicitly on audit tables
+- Set Vector sink buffer to `type = "disk"` — the default in-memory buffer silently drops events when ClickHouse is unavailable
+
+---
+
+### 5. No Audit of Audit-Log Access — §164.312(b)
+
+Grafana queries against ClickHouse constitute access to ePHI audit trails. Those accesses are not themselves logged or reviewed.
+
+**Fix:** Enable ClickHouse query logging and retain Grafana access logs. Review them periodically as part of your access management program.
+
+---
+
+### 6. Failed Login Attempts Not Captured — §164.312(d)
+
+`push_usage_log` only runs when explicitly called by the application. Django's `user_login_failed` signal is not wired, so brute-force attacks against patient portals leave no trace in the audit trail.
+
+**Fix:** Wire `user_login_failed` (and optionally `user_logged_out`) signals in `apps.py:ready()`.
+
+---
+
+### 7. Admin Interface Excluded from Logging — §164.308(a)(1)
+
+`UNREGISTERED_URLS` defaults include `r"^/admin/"` and `LogEntry` is in `UNREGISTERED_CLASSES`. Superuser admin actions carry the highest insider-threat risk and must be in the audit trail.
+
+**Fix:** Remove `^/admin/` from the default exclusion list and remove `LogEntry` from `UNREGISTERED_CLASSES`, or capture admin actions via a dedicated signal.
+
+---
+
+### 8. Acting User's `sex` and `date_of_birth` in Every Log Entry
+
+`get_user_details()` in `middleware.py:66–73` captures `sex` and `date_of_birth` of the user performing the action — not the patient. This unnecessarily expands the ePHI footprint across every single log entry and is directly at risk from point 1 (Sentry).
+
+**Fix:** Strip `sex` and `date_of_birth` from `get_user_details()`. Audit identity only needs `user_id`, `email`, and `role`.
+
+---
+
+## Medium Priority
+
+### 9. `pre_save` + `on_commit` Double-Logging
+
+`handle_pre_save` in `signals.py` calls `push_log`, which wraps emission in `transaction.on_commit`. The pre-commit state semantic is lost since the log is deferred to after commit anyway. Every save emits two entries: PRE_CREATE + CREATE (or PRE_UPDATE + UPDATE), doubling ClickHouse storage for every write.
+
+**Fix:** Remove the `pre_save` signals unless there is a documented use case for capturing pre-commit field state.
+
+---
+
+### 10. Bulk Operations Log Only the First Object's Repr
+
+`signals.py:84–91` — `bulk_create_with_signals` logs `instance_repr` for `created_objs[0]` only, with a `total_count` field. If 500 patient records are bulk-created, the audit shows only one record's state.
+
+**Fix:** Either log all object IDs in the `extra` field, or formally document that bulk operations are audited at the batch level only (not per-record).
+
+---
+
+### 11. SFTP Client Uses `AutoAddPolicy` — `protocols.py:131`
+
+`paramiko.AutoAddPolicy()` accepts any host key silently, making PHI file transfers vulnerable to man-in-the-middle attacks.
+
+**Fix:** Use `paramiko.RejectPolicy()` with explicitly pinned trusted host keys.
+
+---
+
+### 12. Celery / Async Context Loses User Identity Silently
+
+Background Celery tasks that trigger model saves have no request context. `get_user_details()` returns `"", {}` silently — audit entries for async PHI processing have no actor identity, making them useless for accountability.
+
+**Fix:** Explicitly inject the acting user into task context and call `set_current_user()` at the start of tasks that perform auditable operations.
+
+---
+
+## Architecture-Specific
+
+### 13. Silent Log Loss on Container Crash
+
+`transaction.on_commit` in `signals.py:150` defers the audit log write until after the database commits. If the container crashes in the window between DB commit and stdout emission, the database change is committed but the audit event is never emitted — silently lost with no fallback.
+
+**Fix:** Document this as a known gap in the threat model, or add a DB-side audit table as a secondary sink for critical events.
+
+---
+
+### 14. Vector Sink Buffer Not Configured for Durability
+
+The default Vector buffer is in-memory. If ClickHouse is temporarily unavailable, events in the buffer are dropped with no recovery.
+
+**Fix:** Set `type = "disk"` with a defined `max_size` in the Vector ClickHouse sink buffer configuration.
+
+```toml
+[sinks.clickhouse.buffer]
+type = "disk"
+max_size = 268435488  # 256MB
+when_full = "block"
+```

django_activity_audit-1.3.0.dev19/docs/structlog-integration.md

@@ -0,0 +1,419 @@
+# Structlog Integration — Design & Migration Guide
+
+> Authored: 2026-06-16
+> Scope: Evaluating structlog as a replacement / complement to the stdlib `logging` layer in `django-activity-audit`
+
+---
+
+## Current Architecture (Baseline)
+
+| Component | File | Responsibility |
+|-----------|------|----------------|
+| Custom log levels (`AUDIT=21`, `API=22`, `LOGIN=23`) | `logger_levels.py` | Monkey-patched onto `logging.Logger` |
+| Named loggers (`audit.model`, `audit.request`, `audit.login`) | `signals.py:21`, `middleware.py:16`, `utils.py:150` | One logger per concern |
+| Context carriers (`request_id`, `user_id`) | `middleware.py:8–82` | `asgiref.local.Local()` thread-locals |
+| Payload construction | `signals.py:123–152` (`push_log`) | Manually builds dict, passed as `extra={}` |
+| Formatters | `formatters.py` | Manually serialize `LogRecord.extra` to JSON |
+| Handlers | `handlers.py` | `RotatingFileHandler` + async `QueueHandler` variants |
+
+### What push_log() does today
+
+```python
+# signals.py:123-152
+def push_log(message, model, event_type, instance_id, instance_repr, extra={}):
+    user_id, user_info = get_user_details()      # pulls from thread-local
+    request_id = get_request_id()                # pulls from thread-local
+    payload = {
+        "model": model,
+        "event_type": event_type,
+        "request_id": request_id or "",
+        "user_id": user_id,
+        "user_info": user_info,
+        "instance_id": str(instance_id),
+        "instance_repr": instance_repr,
+        "extra": extra,
+    }
+    transaction.on_commit(lambda: logger.audit(message, extra=payload))
+```
+
+Every field is packed manually, every call site must import and invoke `get_request_id()` / `get_user_details()`.
+
+---
+
+## Pros of Structlog
+
+### 1. Context binding replaces manual dict packing
+
+With structlog, fields bound at request entry flow automatically to every log call in that request — no explicit retrieval needed:
+
+```python
+# middleware.py — bind once at request start
+import structlog.contextvars as ctx
+
+ctx.bind_contextvars(
+    request_id=request_id,
+    user_id=user_id,
+    user_info=user_info,
+)
+
+# signals.py — push_log becomes lean
+log = structlog.get_logger("audit.model")
+
+def push_log(message, model, event_type, instance_id, instance_repr, extra={}):
+    transaction.on_commit(lambda: log.audit(
+        message,
+        model=model,
+        event_type=event_type,
+        instance_id=str(instance_id),
+        instance_repr=instance_repr,
+        extra=extra,
+    ))
+    # request_id, user_id, user_info injected automatically by merge_contextvars
+```
+
+### 2. `structlog.contextvars` replaces `asgiref.local.Local()`
+
+The entire `_thread_locals` block in `middleware.py:8–82` (`set_request_id`, `get_request_id`, `set_current_request`, `get_current_user`, `clear_request`, etc.) is replaced by three calls:
+
+```python
+# request start
+structlog.contextvars.bind_contextvars(request_id=uuid, user_id=uid, user_info=info)
+
+# request end (in finally block)
+structlog.contextvars.clear_contextvars()
+```
+
+`contextvars` is async-native — it scopes to the current `asyncio.Task`, so concurrent async requests never bleed context into each other. The current `asgiref.local.Local()` approach requires careful `clear_request()` discipline to avoid leaks (see `improvements.md` — issue #7).
+
+### 3. Processor pipeline — composable and testable
+
+The four monolithic formatters (`AppFormatter`, `APIFormatter`, `AuditFormatter`, `LoginFormatter`) in `formatters.py` each manually extract fields from `LogRecord` and serialize to JSON (~150 lines total). Structlog replaces them with a composable processor list:
+
+```python
+import structlog
+from structlog.processors import CallsiteParameter
+
+shared_processors = [
+    structlog.contextvars.merge_contextvars,          # inject request_id, user_id, user_info
+    structlog.processors.add_log_level,               # adds "level" key
+    structlog.processors.TimeStamper(fmt="iso"),      # ISO 8601 timestamp
+    structlog.processors.CallsiteParameterAdder([     # file + line — see below
+        CallsiteParameter.FILENAME,
+        CallsiteParameter.LINENO,
+        CallsiteParameter.FUNC_NAME,
+    ]),
+    structlog.processors.JSONRenderer(),              # final JSON serialization
+]
+
+structlog.configure(
+    processors=shared_processors,
+    wrapper_class=structlog.make_filtering_bound_logger(logging.DEBUG),
+    context_class=dict,
+    logger_factory=structlog.PrintLoggerFactory(),
+)
+```
+
+Each processor is a pure function — easy to test or swap individually. Adding a new field means appending one processor, not editing four formatters.
+
+### 4. `CallsiteParameterAdder` — file and line in every signal log
+
+**This directly addresses the question: "when performing audit action in signals, can I get file local too along logger?"**
+
+`CallsiteParameterAdder` walks the call stack once per log call and injects:
+
+| Parameter | Captured value (example) |
+|-----------|--------------------------|
+| `FILENAME` | `signals.py` |
+| `LINENO` | `146` |
+| `FUNC_NAME` | `push_log` |
+| `MODULE` | `signals` |
+| `PATHNAME` | `/app/activity_audit/signals.py` |
+
+No changes to `push_log()` — the processor chain handles it. Every `push_log()` call gets:
+
+```json
+{
+    "timestamp": "2026-06-16T10:22:45.123Z",
+    "level": "audit",
+    "event": "CREATE event for Author (id: abc123)",
+    "filename": "signals.py",
+    "lineno": 146,
+    "func_name": "push_log",
+    "model": "Author",
+    "event_type": "CREATE",
+    "request_id": "f3c9a1b2-...",
+    "user_id": "cae8ffb4-..."
+}
+```
+
+> If you want the callsite that triggered `.save()` in user code (not `signals.py` itself), that requires `inspect.stack()` traversal. This is expensive and fragile — the signal-layer callsite is the correct and meaningful audit origin for most use cases.
+
+### 5. `structlog.testing.capture_logs()` — structured test assertions
+
+Current tests assert against formatted log strings or check handler call counts. With structlog:
+
+```python
+import structlog.testing
+
+def test_create_event_logged(db):
+    with structlog.testing.capture_logs() as logs:
+        Author.objects.create(name="Test", bio="Bio")
+
+    audit_logs = [l for l in logs if l.get("event_type") == "CREATE"]
+    assert len(audit_logs) == 1
+    assert audit_logs[0]["model"] == "Author"
+    assert audit_logs[0]["event_type"] == "CREATE"
+    assert "instance_repr" in audit_logs[0]
+```
+
+No string parsing. No mock handlers. The captured entries are plain dicts.
+
+### 6. Lazy rendering — zero overhead when filtered
+
+`push_log()` today builds the full payload dict unconditionally, even if `AUDIT` level is filtered out by the handler. Structlog defers all dict construction and serialization until the processor chain confirms the level passes — filtered calls are nearly free.
+
+### 7. Per-logger context with `bind()`
+
+Signal handlers can pre-bind model-level context at module load:
+
+```python
+# signals.py
+log = structlog.get_logger("audit.model")
+
+def push_log(message, model, event_type, instance_id, instance_repr, extra={}):
+    bound = log.bind(model=model, event_type=event_type)
+    transaction.on_commit(
+        lambda: bound.audit(message, instance_id=str(instance_id), ...)
+    )
+```
+
+The bound logger carries `model` and `event_type` into all subsequent calls — useful when a signal handler emits multiple events in sequence.
+
+---
+
+## Cons of Structlog
+
+### 1. Custom log levels are second-class citizens
+
+`AUDIT=21`, `API=22`, `LOGIN=23` are monkey-patched onto `logging.Logger` in `logger_levels.py`. Structlog's `BoundLogger` has no `.audit()` / `.api()` / `.login()` methods by default.
+
+**Mitigation:** Use `structlog.make_filtering_bound_logger()` with a custom wrapper:
+
+```python
+import structlog
+
+class AuditBoundLogger(structlog.stdlib.BoundLogger):
+    def audit(self, event, **kw):
+        return self._proxy_to_logger("audit", event, **kw)
+
+    def api(self, event, **kw):
+        return self._proxy_to_logger("api", event, **kw)
+
+    def login(self, event, **kw):
+        return self._proxy_to_logger("login", event, **kw)
+
+structlog.configure(wrapper_class=AuditBoundLogger, ...)
+```
+
+This requires registering the custom integer levels on the stdlib side first (same as now via `logger_levels.py`), then bridging through `structlog.stdlib.ProcessorFormatter`.
+
+### 2. Two-layer configuration when using stdlib handlers
+
+If the existing `RotatingFileHandler` / `QueueHandler` chain is kept (to avoid rewriting the async handler infrastructure), both layers must be configured:
+
+```
+structlog processor chain  →  stdlib logging.Logger  →  existing handlers
+```
+
+The bridge is `structlog.stdlib.ProcessorFormatter` — it wraps the processor chain as a stdlib `Formatter`. This is documented and supported but adds conceptual overhead and a config split between `structlog.configure()` and Django's `LOGGING` dict.
+
+### 3. Significant migration surface
+
+Every `logger.audit(msg, extra=payload)` call across `signals.py`, `middleware.py`, `protocols.py`, and `utils.py` must change. The custom handlers (`AuditLogHandler`, `APILogHandler`) extract fields from `LogRecord.__dict__` populated by `extra=` — that extraction logic must be rewritten or the handlers retired.
+
+### 4. Existing formatters become redundant
+
+`AuditFormatter`, `APIFormatter`, `LoginFormatter`, `AppFormatter` (~200 lines in `formatters.py`) produce the same JSON that structlog's `JSONRenderer` would generate. They become dead code — a clean break, but a breaking change for any downstream project that subclassed them.
+
+### 5. Added dependency
+
+`structlog` is a mandatory new dependency for a library package. Not all consumers will have it. A clean opt-in design (e.g. `pip install django-activity-audit[structlog]`) is needed.
+
+---
+
+## Summary: Pros vs Cons
+
+| | Structlog | Current stdlib |
+|--|-----------|----------------|
+| Context propagation | `bind_contextvars` — automatic, async-safe | `asgiref.local.Local()` — manual, leak-prone |
+| File/line in logs | `CallsiteParameterAdder` — zero call-site code | Not captured in audit formatter |
+| Payload construction | Keyword args on log call | Manual dict + `extra={}` |
+| Formatter logic | Composable processor list | ~200 lines across 4 classes |
+| Test assertions | `capture_logs()` → typed dicts | String matching / mock handlers |
+| Performance | Lazy — skipped if level filtered | Dict always constructed |
+| Custom log levels | Requires `BoundLogger` wrapper | Monkey-patched, works today |
+| Handler compatibility | Needs `ProcessorFormatter` bridge | Works natively |
+| Migration cost | High — all call sites change | Zero |
+| Dependency | New required dep | None |
+
+---
+
+## Recommended Migration Strategy
+
+### Phase 1 — Hybrid: structlog processors, stdlib handlers (low risk)
+
+Keep all existing handlers and Django `LOGGING` config. Replace the formatters with `structlog.stdlib.ProcessorFormatter`:
+
+```python
+# formatters.py replacement
+import structlog
+from structlog.stdlib import ProcessorFormatter
+
+renderer = ProcessorFormatter(
+    processor=structlog.processors.JSONRenderer(),
+    foreign_pre_chain=[
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.CallsiteParameterAdder([
+            structlog.processors.CallsiteParameter.FILENAME,
+            structlog.processors.CallsiteParameter.LINENO,
+            structlog.processors.CallsiteParameter.FUNC_NAME,
+        ]),
+    ],
+)
+```
+
+Wire it into the existing Django `LOGGING` dict:
+
+```python
+LOGGING = {
+    "formatters": {
+        "audit_json": {"()": lambda: renderer},
+    },
+    "handlers": {
+        "audit_file": {
+            **get_async_audit_handler(filename="audit_logs/audit.log"),
+            "formatter": "audit_json",
+        },
+        ...
+    },
+}
+```
+
+This unlocks `CallsiteParameterAdder` and cleaner processor composition with zero changes to handlers or call sites.
+
+### Phase 2 — Context migration
+
+Replace `asgiref.local.Local()` thread-locals in `middleware.py:8–82` with `structlog.contextvars`:
+
+```python
+# middleware.py
+
+import structlog.contextvars as ctx
+
+class AuditLoggingMiddleware:
+    def __call__(self, request):
+        request_id = str(uuid.uuid4())
+        ctx.clear_contextvars()
+        ctx.bind_contextvars(request_id=request_id)
+        try:
+            response = self.get_response(request)
+            user_id, user_info = _extract_user(request)
+            ctx.bind_contextvars(user_id=user_id, user_info=user_info)
+            ...
+        finally:
+            ctx.clear_contextvars()
+        return response
+```
+
+Remove `get_request_id()`, `get_user_details()`, `set_current_request()`, `clear_request()` from `push_log()` — the processor chain picks them up automatically via `merge_contextvars`.
+
+This also fixes the thread-local leak described in `improvements.md` (issue #7) as a side effect.
+
+### Phase 3 — Call-site cleanup
+
+Refactor `push_log()` to use structlog native calls, retire `extra={}` pattern, update tests to use `capture_logs()`.
+
+---
+
+## File/Line Info in Signal Handlers — Implementation Detail
+
+Add `CallsiteParameterAdder` to the processor chain (Phase 1). The processor requires a `_record` key to be present, which `ProcessorFormatter` injects automatically when bridging from stdlib.
+
+Every log entry emitted from `push_log()` (signals.py:146) will include:
+
+```json
+{
+    "filename": "signals.py",
+    "lineno": 146,
+    "func_name": "push_log"
+}
+```
+
+To also capture the Django model file that owns the `.save()` call, add a lightweight stack inspector:
+
+```python
+import inspect
+
+def _get_save_callsite() -> dict:
+    for frame_info in inspect.stack():
+        if frame_info.filename.endswith("signals.py"):
+            continue
+        if frame_info.function in ("save", "bulk_create", "bulk_update"):
+            continue
+        return {
+            "trigger_file": frame_info.filename,
+            "trigger_line": frame_info.lineno,
+            "trigger_func": frame_info.function,
+        }
+    return {}
+```
+
+Pass the result as `extra` in `push_log()`. Use sparingly — `inspect.stack()` is expensive and should be guarded behind a debug flag or sampled.
+
+---
+
+## Output Log Shape (Post-Migration)
+
+```json
+{
+    "timestamp": "2026-06-16T10:22:45.123Z",
+    "level": "audit",
+    "logger": "audit.model",
+    "event": "CREATE event for Author (id: abc123)",
+    "filename": "signals.py",
+    "lineno": 146,
+    "func_name": "push_log",
+    "request_id": "f3c9a1b2-0001-4abc-beef-deadbeef0001",
+    "user_id": "cae8ffb4-ba52-409c-9a6f-e10362bfaf97",
+    "user_info": {
+        "email": "user@example.com",
+        "first_name": "Ada",
+        "last_name": "Lovelace"
+    },
+    "model": "Author",
+    "event_type": "CREATE",
+    "instance_id": "9f1b2c3d-...",
+    "instance_repr": { "name": "Ada Lovelace", "bio": "Mathematician" },
+    "extra": {}
+}
+```
+
+All fields from the current `AuditFormatter` output are preserved. New fields: `filename`, `lineno`, `func_name`. The `request_id` / `user_id` / `user_info` fields are no longer passed manually — they come from the processor chain.
+
+---
+
+## Dependency
+
+```toml
+# pyproject.toml
+[project.optional-dependencies]
+structlog = ["structlog>=24.0"]
+```
+
+```bash
+pip install django-activity-audit[structlog]
+```
+
+The core package remains dependency-free. Structlog features activate only when the optional extra is installed and `structlog.configure()` is called by the host application.

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-activity-audit"
-version = "1.3.0.dev18"
+version = "1.3.0.dev19"
 description = "A Django package for easy CRUD operation logging and container logs"
 authors = [
     { name = "Shreeshan", email = "shreeshan256@gmail.com" }
@@ -50,7 +50,9 @@ test = [
   "pytest-django>=4.0.0",
   "pytest-cov>=4.0.0",
   "djangorestframework>=3.14.0",
+  "structlog>=24.0",
 ]
+structlog = ["structlog>=24.0"]
 
 [build-system]
 requires = ["hatchling"]

django_activity_audit-1.3.0.dev18/activity_audit/apps.py

@@ -1,22 +0,0 @@
-from django.apps import AppConfig
-
-
-class AuditLoggingConfig(AppConfig):
-    default_auto_field = "django.db.models.BigAutoField"
-    name = "activity_audit"
-    verbose_name = "Django Activity Audit"
-
-    def ready(self):
-        # Import and register custom log levels
-        from . import logger_levels
-
-        # Force registration of custom levels
-        logger_levels.AUDIT
-        logger_levels.API
-        logger_levels.LOGIN
-
-        # Populate UNREGISTERED_CLASSES (requires app registry to be ready)
-        from . import unregistered  # noqa
-
-        # Initialize signals
-        from . import signals  # noqa