Feature: Update consumer logging to include task ID for log correlation (#12510)

src/paperless/logging.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar
+
+consume_task_id: ContextVar[str] = ContextVar("consume_task_id", default="")
+
+
+class ConsumeTaskFormatter(logging.Formatter):
+    """
+    Logging formatter that prepends a short task correlation ID to messages
+    emitted during document consumption.
+
+    The ID is the first 8 characters of the Celery task UUID, set via the
+    ``consume_task_id`` ContextVar at the entry of ``consume_file``.  When
+    the ContextVar is empty (any log outside a consume task) no prefix is
+    added and the output is identical to the standard verbose format.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            fmt="[{asctime}] [{levelname}] [{name}] {task_prefix}{message}",
+            style="{",
+            validate=False,  # {task_prefix} is not a standard LogRecord attribute, so Python's
+            # init-time format-string validation would raise ValueError without
+            # this. Runtime safety comes from format() always setting
+            # record.task_prefix before calling super().format().
+        )
+
+    def format(self, record: logging.LogRecord) -> str:
+        task_id = consume_task_id.get()
+        record.task_prefix = f"[{task_id}] " if task_id else ""
+        return super().format(record)

src/paperless/settings/__init__.py

@@ -592,8 +592,7 @@ LOGGING = {
     "disable_existing_loggers": False,
     "formatters": {
         "verbose": {
-            "format": "[{asctime}] [{levelname}] [{name}] {message}",
-            "style": "{",
+            "()": "paperless.logging.ConsumeTaskFormatter",
         },
         "simple": {
             "format": "{levelname} {message}",

src/paperless/tests/test_logging.py

@@ -0,0 +1,34 @@
+import logging
+
+from paperless.logging import ConsumeTaskFormatter
+from paperless.logging import consume_task_id
+
+
+def _make_record(msg: str = "Test message") -> logging.LogRecord:
+    return logging.LogRecord(
+        name="paperless.consumer",
+        level=logging.INFO,
+        pathname="",
+        lineno=0,
+        msg=msg,
+        args=(),
+        exc_info=None,
+    )
+
+
+def test_formatter_includes_task_id_when_set():
+    token = consume_task_id.set("a8098c1a")
+    try:
+        formatter = ConsumeTaskFormatter()
+        output = formatter.format(_make_record())
+        assert "[a8098c1a] Test message" in output
+    finally:
+        consume_task_id.reset(token)
+
+
+def test_formatter_omits_prefix_when_no_task_id():
+    # ContextVar default is "" — no task active
+    formatter = ConsumeTaskFormatter()
+    output = formatter.format(_make_record())
+    assert "[] " not in output
+    assert "Test message" in output