normalize Throwable only in the exception context key per PSR-3

Author: michalsn

app/Config/Logger.php

@@ -73,8 +73,8 @@ class Logger extends BaseConfig
      * --------------------------------------------------------------------------
      *
      * When enabled, context keys not used as placeholders in the message are
-     * passed to handlers as structured data. Any Throwable instances found in
-     * the context are automatically normalized to an array representation.
+     * passed to handlers as structured data. Per PSR-3, any ``Throwable`` instance
+     * in the ``exception`` key is automatically normalized to an array representation.
      */
     public bool $logContext = false;
 
@@ -83,8 +83,8 @@ class Logger extends BaseConfig
      * Whether to include the stack trace for Throwables in context
      * --------------------------------------------------------------------------
      *
-     * When enabled, the stack trace is included when a Throwable is found in
-     * the context and normalized. Only relevant when $logContext is true.
+     * When enabled, the stack trace is included when normalizing a Throwable
+     * in the ``exception`` context key. Only relevant when $logContext is true.
      */
     public bool $logContextTrace = false;
 

system/Log/Logger.php

@@ -334,30 +334,32 @@ public function log($level, string|Stringable $message, array $context = []): vo
 
     /**
      * Normalizes context values for structured logging.
-     * Converts any Throwable instances into an array representation.
+     * Per PSR-3, if an Exception is given to produce a stack trace, it MUST be
+     * in a key named "exception". Only that key is converted into an array
+     * representation.
      *
      * @param array<string, mixed> $context
      *
      * @return array<string, mixed>
      */
     protected function normalizeContext(array $context): array
     {
-        foreach ($context as $key => $value) {
-            if ($value instanceof Throwable) {
-                $normalized = [
-                    'class'   => $value::class,
-                    'message' => $value->getMessage(),
-                    'code'    => $value->getCode(),
-                    'file'    => clean_path($value->getFile()),
-                    'line'    => $value->getLine(),
-                ];
-
-                if ($this->logContextTrace) {
-                    $normalized['trace'] = $value->getTraceAsString();
-                }
-
-                $context[$key] = $normalized;
+        if (isset($context['exception']) && $context['exception'] instanceof Throwable) {
+            $value = $context['exception'];
+
+            $normalized = [
+                'class'   => $value::class,
+                'message' => $value->getMessage(),
+                'code'    => $value->getCode(),
+                'file'    => clean_path($value->getFile()),
+                'line'    => $value->getLine(),
+            ];
+
+            if ($this->logContextTrace) {
+                $normalized['trace'] = $value->getTraceAsString();
             }
+
+            $context['exception'] = $normalized;
         }
 
         return $context;

tests/system/Log/LoggerTest.php

@@ -590,6 +590,25 @@ public function testLogContextNormalizesThrowable(): void
         $this->assertArrayNotHasKey('trace', $normalized);
     }
 
+    public function testLogContextDoesNotNormalizeThrowableUnderArbitraryKey(): void
+    {
+        $config             = new LoggerConfig();
+        $config->logContext = true;
+
+        $logger = new Logger($config);
+
+        try {
+            throw new RuntimeException('Something went wrong');
+        } catch (RuntimeException $e) {
+            $logger->log('error', 'An error occurred', ['error' => $e]);
+        }
+
+        $contexts = TestHandler::getContexts();
+
+        // Per PSR-3, only the 'exception' key is normalized; other keys are left as-is.
+        $this->assertInstanceOf(RuntimeException::class, $contexts[0]['error']);
+    }
+
     public function testLogContextNormalizesThrowableWithTrace(): void
     {
         $config                  = new LoggerConfig();

user_guide_src/source/changelogs/v4.8.0.rst

@@ -176,7 +176,7 @@ Libraries
 
 - **Context**: This new feature allows you to easily set and retrieve normal or hidden contextual data for the current request. See :ref:`Context <context>` for details.
 - **Logging:** Log handlers now receive the full context array as a third argument to ``handle()``. When ``$logGlobalContext`` is enabled, the CI global context is available under the ``HandlerInterface::GLOBAL_CONTEXT_KEY`` key. Built-in handlers append it to the log output; custom handlers can use it for structured logging.
-- **Logging:** Added :ref:`per-call context logging <logging-per-call-context>` with three new ``Config\Logger`` options (``$logContext``, ``$logContextTrace``, ``$logContextUsedKeys``). ``Throwable`` instances in context are automatically normalized to a meaningful array. All options default to ``false``.
+- **Logging:** Added :ref:`per-call context logging <logging-per-call-context>` with three new ``Config\Logger`` options (``$logContext``, ``$logContextTrace``, ``$logContextUsedKeys``). Per PSR-3, a ``Throwable`` in the ``exception`` context key is automatically normalized to a meaningful array. All options default to ``false``.
 
 Helpers and Functions
 =====================

user_guide_src/source/general/logging.rst

@@ -169,8 +169,9 @@ text), but you can keep them by setting ``$logContextUsedKeys = true``.
 
 **Throwable normalization**
 
-Any ``Throwable`` instance (exception or error) found in the context is automatically
-normalized into a meaningful array instead of being serialized as an empty object:
+Per PSR-3, a ``Throwable`` instance must be passed under the ``exception`` key to be
+handled specially. When found there, it is automatically normalized into a meaningful
+array instead of being serialized as an empty object:
 
 .. literalinclude:: logging/008.php