docs(logger): document arbitrary kwargs support in logger

Author: heitorlessa

docs/core/logger.md

@@ -158,7 +158,7 @@ To ease routine tasks like extracting correlation ID from popular event sources,
 You can append additional keys using either mechanism:
 
 * Persist new keys across all future log messages via `append_keys` method
-* Add additional keys on a per log message basis via `extra` parameter
+* Add additional keys on a per log message basis as a keyword=value, or via `extra` parameter
 
 #### append_keys method
 
@@ -184,14 +184,33 @@ You can append your own keys to your existing Logger via `append_keys(**addition
 
     This example will add `order_id` if its value is not empty, and in subsequent invocations where `order_id` might not be present it'll remove it from the Logger.
 
+#### ephemeral metadata
+
+You can pass an arbitrary number of keyword arguments (kwargs) to all log level's methods, e.g. `logger.info, logger.warning`.
+
+Two common use cases for this feature is to enrich log statements with additional metadata, or only add certain keys conditionally.
+
+!!! info "Any keyword argument added will not be persisted in subsequent messages."
+
+=== "append_keys_kwargs.py"
+
+    ```python hl_lines="8"
+    --8<-- "examples/logger/src/append_keys_kwargs.py"
+    ```
+
+=== "append_keys_kwargs_output.json"
+
+    ```json hl_lines="7"
+    --8<-- "examples/logger/src/append_keys_kwargs_output.json"
+    ```
+
 #### extra parameter
 
 Extra parameter is available for all log levels' methods, as implemented in the standard logging library - e.g. `logger.info, logger.warning`.
 
 It accepts any dictionary, and all keyword arguments will be added as part of the root structure of the logs for that log statement.
 
-???+ info
-    Any keyword argument added using `extra` will not be persisted for subsequent messages.
+!!! info "Any keyword argument added using `extra` will not be persisted in subsequent messages."
 
 === "append_keys_extra.py"
 

examples/logger/src/append_keys_kwargs.py

@@ -0,0 +1,10 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+def handler(event: dict, context: LambdaContext) -> str:
+    logger.info("Collecting payment", request_id="1123")
+
+    return "hello world"

examples/logger/src/append_keys_kwargs_output.json

@@ -0,0 +1,8 @@
+{
+    "level": "INFO",
+    "location": "collect.handler:8",
+    "message": "Collecting payment",
+    "timestamp": "2022-11-26 11:47:12,494+0200",
+    "service": "payment",
+    "request_id": "1123"
+}