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

django_activity_audit-1.3.0.dev20/.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.dev20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-activity-audit
-Version: 1.3.0.dev18
+Version: 1.3.0.dev20
 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
@@ -26,6 +26,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Requires-Dist: django<6.0,>=4.2
+Requires-Dist: orjson>=3.0
+Requires-Dist: structlog>=24.0
 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'
@@ -59,6 +61,8 @@ A Django package that extends the default logging mechanism to track CRUD operat
 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:
 ```python
 INSTALLED_APPS = [
@@ -76,47 +80,101 @@ MIDDLEWARE = [
 ```
 
 4. Configure logging in settings.py:
+
+Import the formatter helpers from `activity_audit.config`:
+
 ```python
-from activity_audit import *
+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):
+
+```python
+from activity_audit.config import get_plain_formatter, get_stdlib_formatter
 
 LOGGING = {
     "version": 1,
     "disable_existing_loggers": False,
     "formatters": {
-        "json": get_json_formatter(),
-        "verbose": get_console_formatter(),
+        "structlog": get_stdlib_formatter(),
+        "default":   get_plain_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(),
+        "console":        {"class": "logging.StreamHandler", "formatter": "default"},
+        "console_struct": {"class": "logging.StreamHandler", "formatter": "structlog"},
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],   # plain text fallback for all loggers
     },
-    "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,
-        },
-    }
+        # 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):
+
+```python
+"root": {
+    "level": "INFO",
+    "handlers": ["console"],
+}
+```
+
+---
+
+### When to add a logger entry
+
+Add an explicit logger entry when you need **any** of the following:
+
+| 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`:
+
+```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"`):
 ```python
 AUDIT_SERVICE_NAME = "my_service"

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

@@ -19,6 +19,8 @@ A Django package that extends the default logging mechanism to track CRUD operat
 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:
 ```python
 INSTALLED_APPS = [
@@ -36,47 +38,101 @@ MIDDLEWARE = [
 ```
 
 4. Configure logging in settings.py:
+
+Import the formatter helpers from `activity_audit.config`:
+
 ```python
-from activity_audit import *
+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):
+
+```python
+from activity_audit.config import get_plain_formatter, get_stdlib_formatter
 
 LOGGING = {
     "version": 1,
     "disable_existing_loggers": False,
     "formatters": {
-        "json": get_json_formatter(),
-        "verbose": get_console_formatter(),
+        "structlog": get_stdlib_formatter(),
+        "default":   get_plain_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(),
+        "console":        {"class": "logging.StreamHandler", "formatter": "default"},
+        "console_struct": {"class": "logging.StreamHandler", "formatter": "structlog"},
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],   # plain text fallback for all loggers
     },
-    "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,
-        },
-    }
+        # 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):
+
+```python
+"root": {
+    "level": "INFO",
+    "handlers": ["console"],
+}
+```
+
+---
+
+### When to add a logger entry
+
+Add an explicit logger entry when you need **any** of the following:
+
+| 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`:
+
+```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"`):
 ```python
 AUDIT_SERVICE_NAME = "my_service"

{django_activity_audit-1.3.0.dev18 → django_activity_audit-1.3.0.dev20}/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.dev20/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.dev20/activity_audit/config.py

@@ -0,0 +1,82 @@
+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_plain_formatter() -> dict:
+    """
+    LOGGING formatter dict that routes stdlib loggers through the structlog
+    processor chain but renders as plain text instead of JSON. Use for local
+    development when human-readable output is preferred over structured JSON.
+    """
+    return {
+        "()": structlog.stdlib.ProcessorFormatter,
+        "processors": [
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            structlog.dev.ConsoleRenderer(colors=False),
+        ],
+        "foreign_pre_chain": shared_processors,
+    }
+
+
+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.dev20}/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.dev20}/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.dev20}/activity_audit/middleware.py

@@ -1,21 +1,26 @@
-import contextlib
 import json
-import logging
 import re
 import time
 import uuid
 
-from asgiref.local import Local
-from asgiref.sync import iscoroutinefunction, markcoroutinefunction, sync_to_async
+from contextvars import ContextVar
+
+import structlog.contextvars as ctx
+
+from asgiref.sync import (
+    iscoroutinefunction,
+    markcoroutinefunction,
+)
 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()
+_request_var: ContextVar = ContextVar("current_request", default=None)
 
 
 class MockRequest:
@@ -26,19 +31,11 @@ class MockRequest:
 
 
 def get_current_request():
-    return getattr(_thread_locals, "request", None)
+    return _request_var.get()
 
 
 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
+    _request_var.set(request)
 
 
 def get_current_user():
@@ -49,11 +46,11 @@ def get_current_user():
 
 
 def set_current_user(user):
-    try:
-        _thread_locals.request.user = user
-    except AttributeError:
-        request = MockRequest(user=user)
-        _thread_locals.request = request
+    request = _request_var.get()
+    if request is not None:
+        request.user = user
+    else:
+        _request_var.set(MockRequest(user=user))
 
 
 def get_user_details():
@@ -75,10 +72,7 @@ def get_user_details():
 
 
 def clear_request():
-    with contextlib.suppress(AttributeError):
-        del _thread_locals.request
-    with contextlib.suppress(AttributeError):
-        del _thread_locals.request_id
+    _request_var.set(None)
 
 
 def should_log_url(url):
@@ -135,7 +129,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 +139,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 +167,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 +189,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 +213,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,
@@ -250,11 +240,8 @@ class AuditLoggingMiddleware(MiddlewareMixin):
         end_time = time.time()
 
         # Capture user details AFTER authentication has happened
-        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
+        user_id, user_info = get_user_details()
+        ctx.bind_contextvars(user_id=user_id, user_info=user_info)
 
         # TODO: Find way to add status code to response_data
 
@@ -276,12 +263,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