From 1fc7471fc4a3fdaa82a8f9316c8b4d047f1942d8 Mon Sep 17 00:00:00 2001 From: oyiz-michael Date: Sat, 20 Dec 2025 01:24:45 +0000 Subject: [PATCH] docs: clarify append_context_keys behavior with overlapping keys Fixes #7690 Clarifies that append_context_keys() removes all added keys on exit, including keys that already existed with the same name. This addresses user confusion about the 'temporarily' behavior when keys overlap. Changes: - Updated docstrings in formatter.py and logger.py with clear warning - Added detailed documentation in logger.md with collision example - Explains that original values are lost when keys overlap - Recommends using append_keys() for persistent keys to avoid collisions This is a documentation-only fix that clarifies current behavior without changing functionality. --- aws_lambda_powertools/logging/formatter.py | 6 ++++++ aws_lambda_powertools/logging/logger.py | 6 ++++++ docs/core/logger.md | 16 ++++++++++++++++ 3 files changed, 28 insertions(+) diff --git a/aws_lambda_powertools/logging/formatter.py b/aws_lambda_powertools/logging/formatter.py index 705ca419823..6be311bee0a 100644 --- a/aws_lambda_powertools/logging/formatter.py +++ b/aws_lambda_powertools/logging/formatter.py @@ -281,6 +281,12 @@ def append_context_keys(self, **additional_keys: Any) -> Generator[None, None, N **additional_keys: Any Key-value pairs to include in the log context during the lifespan of the context manager. + Warning + ------- + All keys added within this context are removed when exiting, even if they existed before. + If a key with the same name already exists, the original value will be lost after the context exits. + To persist keys across multiple log messages, use `append_keys()` instead. + Example -------- logger = Logger(service="example_service") diff --git a/aws_lambda_powertools/logging/logger.py b/aws_lambda_powertools/logging/logger.py index 154d8ee6353..b0371b8a47d 100644 --- a/aws_lambda_powertools/logging/logger.py +++ b/aws_lambda_powertools/logging/logger.py @@ -820,6 +820,12 @@ def append_context_keys(self, **additional_keys: Any) -> Generator[None, None, N **additional_keys: Any Key-value pairs to include in the log context during the lifespan of the context manager. + Warning + ------- + All keys added within this context are removed when exiting, even if they existed before. + If a key with the same name already exists, the original value will be lost after the context exits. + To persist keys across multiple log messages, use `append_keys()` instead. + Example -------- **Logging with contextual keys** diff --git a/docs/core/logger.md b/docs/core/logger.md index 80a4ec4df5b..880b252241c 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -195,6 +195,22 @@ You can append your own keys to your existing Logger via `append_keys(**addition The append_context_keys method allows temporary modification of a Logger instance's context without creating a new logger. It's useful for adding context keys to specific workflows while maintaining the logger's overall state and simplicity. +???+ danger "Important: Keys are removed on context exit, even if they existed before" + All keys added within the context are removed when exiting, **including keys that already existed with the same name**. + + If you need to temporarily override a key's value while preserving the original, use `append_keys()` for persistent keys and avoid key name collisions with `append_context_keys()`. + + **Example of key collision:** + ```python + logger.append_keys(order_id="ORD-123") # Persistent key + logger.info("Order received") # Has order_id="ORD-123" + + with logger.append_context_keys(order_id="ORD-CHILD"): # Overwrites + logger.info("Processing") # Has order_id="ORD-CHILD" + + logger.info("Order completed") # order_id key is now MISSING! + ``` + === "append_context_keys.py" ```python hl_lines="7 8"