Changing documentation and method names

Author: leandrodamascena

Diff for: aws_lambda_powertools/logging/formatter.py

@@ -51,27 +51,29 @@ class BasePowertoolsFormatter(logging.Formatter, metaclass=ABCMeta):
     def append_keys(self, **additional_keys) -> None:
         raise NotImplementedError()
 
-    def append_thread_local_keys(self, **additional_keys) -> None:
-        raise NotImplementedError()
-
     def get_current_keys(self) -> dict[str, Any]:
         return {}
 
-    def get_current_thread_keys(self) -> dict[str, Any]:
-        return {}
-
     def remove_keys(self, keys: Iterable[str]) -> None:
         raise NotImplementedError()
 
-    def remove_thread_local_keys(self, keys: Iterable[str]) -> None:
-        raise NotImplementedError()
-
     @abstractmethod
     def clear_state(self) -> None:
         """Removes any previously added logging keys"""
         raise NotImplementedError()
 
-    def clear_thread_local_keys(self) -> None:
+    # These specific thread-safe methods are necessary to manage shared context in concurrent environments.
+    # They prevent race conditions and ensure data consistency across multiple threads.
+    def thread_safe_append_keys(self, **additional_keys) -> None:
+        raise NotImplementedError()
+
+    def thread_safe_get_current_keys(self) -> dict[str, Any]:
+        return {}
+
+    def thread_safe_remove_keys(self, keys: Iterable[str]) -> None:
+        raise NotImplementedError()
+
+    def thread_safe_clear_keys(self) -> None:
         """Removes any previously added logging keys in a specific thread"""
         raise NotImplementedError()
 
@@ -250,27 +252,33 @@ def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> s
     def append_keys(self, **additional_keys) -> None:
         self.log_format.update(additional_keys)
 
-    def append_thread_local_keys(self, **additional_keys) -> None:
-        set_context_keys(**additional_keys)
-
     def get_current_keys(self) -> dict[str, Any]:
         return self.log_format
 
-    def get_current_thread_keys(self) -> dict[str, Any]:
-        return _get_context().get()
-
     def remove_keys(self, keys: Iterable[str]) -> None:
         for key in keys:
             self.log_format.pop(key, None)
 
-    def remove_thread_local_keys(self, keys: Iterable[str]) -> None:
-        remove_context_keys(keys)
-
     def clear_state(self) -> None:
         self.log_format = dict.fromkeys(self.log_record_order)
         self.log_format.update(**self.keys_combined)
 
-    def clear_thread_local_keys(self) -> None:
+    # These specific thread-safe methods are necessary to manage shared context in concurrent environments.
+    # They prevent race conditions and ensure data consistency across multiple threads.
+    def thread_safe_append_keys(self, **additional_keys) -> None:
+        # Append additional key-value pairs to the context safely in a thread-safe manner.
+        set_context_keys(**additional_keys)
+
+    def thread_safe_get_current_keys(self) -> dict[str, Any]:
+        # Retrieve the current context keys safely in a thread-safe manner.
+        return _get_context().get()
+
+    def thread_safe_remove_keys(self, keys: Iterable[str]) -> None:
+        # Remove specified keys from the context safely in a thread-safe manner.
+        remove_context_keys(keys)
+
+    def thread_safe_clear_keys(self) -> None:
+        # Clear all keys from the context safely in a thread-safe manner.
         clear_context_keys()
 
     @staticmethod

Diff for: aws_lambda_powertools/logging/logger.py

@@ -583,23 +583,29 @@ def debug(
     def append_keys(self, **additional_keys: object) -> None:
         self.registered_formatter.append_keys(**additional_keys)
 
-    def append_thread_local_keys(self, **additional_keys: object) -> None:
-        self.registered_formatter.append_thread_local_keys(**additional_keys)
-
     def get_current_keys(self) -> dict[str, Any]:
         return self.registered_formatter.get_current_keys()
 
-    def get_current_thread_keys(self) -> dict[str, Any]:
-        return self.registered_formatter.get_current_thread_keys()
-
     def remove_keys(self, keys: Iterable[str]) -> None:
         self.registered_formatter.remove_keys(keys)
 
-    def remove_thread_local_keys(self, keys: Iterable[str]) -> None:
-        self.registered_formatter.remove_thread_local_keys(keys)
+    # These specific thread-safe methods are necessary to manage shared context in concurrent environments.
+    # They prevent race conditions and ensure data consistency across multiple threads.
+    def thread_safe_append_keys(self, **additional_keys: object) -> None:
+        # Append additional key-value pairs to the context safely in a thread-safe manner.
+        self.registered_formatter.thread_safe_append_keys(**additional_keys)
+
+    def thread_safe_get_current_keys(self) -> dict[str, Any]:
+        # Retrieve the current context keys safely in a thread-safe manner.
+        return self.registered_formatter.thread_safe_get_current_keys()
+
+    def thread_safe_remove_keys(self, keys: Iterable[str]) -> None:
+        # Remove specified keys from the context safely in a thread-safe manner.
+        self.registered_formatter.thread_safe_remove_keys(keys)
 
-    def clear_thread_local_keys(self) -> None:
-        self.registered_formatter.clear_thread_local_keys()
+    def thread_safe_clear_keys(self) -> None:
+        # Clear all keys from the context safely in a thread-safe manner.
+        self.registered_formatter.thread_safe_clear_keys()
 
     def structure_logs(self, append: bool = False, formatter_options: dict | None = None, **keys) -> None:
         """Sets logging formatting to JSON.
@@ -645,7 +651,7 @@ def structure_logs(self, append: bool = False, formatter_options: dict | None =
 
         # Mode 3
         self.registered_formatter.clear_state()
-        self.registered_formatter.clear_thread_local_keys()
+        self.registered_formatter.thread_safe_clear_keys()
         self.registered_formatter.append_keys(**log_keys)
 
     def set_correlation_id(self, value: str | None) -> None:

Diff for: docs/core/event_handler/api_gateway.md

@@ -128,11 +128,12 @@ Here's an example on how we can handle the `/todos` path.
 
 When using Amazon API Gateway HTTP API to front your Lambda functions, you can use `APIGatewayHttpResolver`.
 
+<!-- markdownlint-disable MD013 -->
 ???+ note
     Using HTTP API v1 payload? Use `APIGatewayRestResolver` instead. `APIGatewayHttpResolver` defaults to v2 payload.
 
-    <!-- markdownlint-disable-next-line MD013 -->
     If you're using Terraform to deploy a HTTP API, note that it defaults the [payload_format_version](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_integration#payload_format_version){target="_blank" rel="nofollow"} value to 1.0 if not specified.
+<!-- markdownlint-enable MD013 -->
 
 ```python hl_lines="5 11" title="Using HTTP API resolver"
 --8<-- "examples/event_handler_rest/src/getting_started_http_api_resolver.py"

Diff for: docs/core/logger.md

@@ -160,13 +160,13 @@ To ease routine tasks like extracting correlation ID from popular event sources,
 You can append additional keys using either mechanism:
 
 * New keys persist across all future log messages via `append_keys` method
-* New keys persist across all future logs in a specific thread via `append_thread_local_keys` method
 * Add additional keys on a per log message basis as a keyword=value, or via `extra` parameter
+* New keys persist across all future logs in a specific thread via `thread_safe_append_keys` method. Check [Working with thread-safe keys](#working-with-thread-safe-keys) section.
 
 #### append_keys method
 
 ???+ warning
-    `append_keys` is not thread-safe, use `append_thread_local_keys` instead
+    `append_keys` is not thread-safe, use [thread_safe_append_keys](#appending-thread-safe-additional-keys) instead
 
 You can append your own keys to your existing Logger via `append_keys(**additional_key_values)` method.
 
@@ -187,22 +187,6 @@ 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.
 
-#### append_thread_local_keys method
-
-You can append your own thread-local keys in your existing Logger via the `append_thread_local_keys` method
-
-=== "append_thread_local_keys.py"
-
-    ```python hl_lines="11"
-    --8<-- "examples/logger/src/append_thread_local_keys.py"
-    ```
-
-=== "append_thread_local_keys_output.json"
-
-    ```json hl_lines="8 9 17 18"
-    --8<-- "examples/logger/src/append_thread_local_keys_output.json"
-    ```
-
 #### ephemeral metadata
 
 You can pass an arbitrary number of keyword arguments (kwargs) to all log level's methods, e.g. `logger.info, logger.warning`.
@@ -248,11 +232,10 @@ It accepts any dictionary, and all keyword arguments will be added as part of th
 You can remove additional keys using either mechanism:
 
 * Remove new keys across all future log messages via `remove_keys` method
-* Remove new keys across all future logs in a specific thread via `remove_thread_local_keys` method
-* Remove **all** new keys across all future logs in a specific thread via `clear_thread_local_keys` method
+* Remove keys persist across all future logs in a specific thread via `thread_safe_remove_keys` method. Check [Working with thread-safe keys](#working-with-thread-safe-keys) section.
 
 ???+ danger
-    Keys added by `append_keys` can only be removed by `remove_keys` and thread-local keys added by `append_thread_local_key` can only be removed by `remove_thread_local_keys` or `clear_thread_local_keys`. Thread-local and normal logger keys are distinct values and can't be manipulated interchangably.
+    Keys added by `append_keys` can only be removed by `remove_keys` and thread-local keys added by `thread_safe_append_keys` can only be removed by `thread_safe_remove_keys` or `thread_safe_clear_keys`. Thread-local and normal logger keys are distinct values and can't be manipulated interchangeably.
 
 #### remove_keys method
 
@@ -270,40 +253,6 @@ You can remove any additional key from Logger state using `remove_keys`.
     --8<-- "examples/logger/src/remove_keys_output.json"
     ```
 
-#### remove_thread_local_keys method
-
-You can remove any additional thread-local keys from Logger using either `remove_thread_local_keys` or `clear_thread_local_keys`.
-
-Use the `remove_thread_local_keys` method to remove a list of thread-local keys that were previously added using the `append_thread_local_keys` method.
-
-=== "remove_thread_local_keys.py"
-
-    ```python hl_lines="13"
-    --8<-- "examples/logger/src/remove_thread_local_keys.py"
-    ```
-
-=== "remove_thread_local_keys_output.json"
-
-    ```json hl_lines="8 9 17 18 26 34"
-    --8<-- "examples/logger/src/remove_thread_local_keys_output.json"
-    ```
-
-#### clear_thread_local_keys method
-
-Use the `clear_thread_local_keys` method to remove all thread-local keys that were previously added using the `append_thread_local_keys` method.
-
-=== "clear_thread_local_keys.py"
-
-    ```python hl_lines="13"
-    --8<-- "examples/logger/src/clear_thread_local_keys.py"
-    ```
-
-=== "clear_thread_local_keys_output.json"
-
-    ```json hl_lines="8 9 17 18"
-    --8<-- "examples/logger/src/clear_thread_local_keys_output.json"
-    ```
-
 #### Clearing all state
 
 Logger is commonly initialized in the global scope. Due to [Lambda Execution Context reuse](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html){target="_blank"}, this means that custom keys can be persisted across invocations. If you want all custom keys to be deleted, you can use `clear_state=True` param in `inject_lambda_context` decorator.
@@ -538,6 +487,68 @@ You can use any of the following built-in JMESPath expressions as part of [injec
 | **APPLICATION_LOAD_BALANCER** | `'headers."x-amzn-trace-id"'`         | ALB X-Ray Trace ID              |
 | **EVENT_BRIDGE**              | `"id"`                                | EventBridge Event ID            |
 
+### Working with thread-safe keys
+
+#### Appending thread-safe additional keys
+
+You can append your own thread-local keys in your existing Logger via the `thread_safe_append_keys` method
+
+=== "thread_safe_append_keys.py"
+
+    ```python hl_lines="11"
+    --8<-- "examples/logger/src/thread_safe_append_keys.py"
+    ```
+
+=== "thread_safe_append_keys_output.json"
+
+    ```json hl_lines="8 9 17 18"
+    --8<-- "examples/logger/src/thread_safe_append_keys_output.json"
+    ```
+
+#### Removing thread-safe additional keys
+
+You can remove any additional thread-local keys from Logger using either `thread_safe_remove_keys` or `thread_safe_clear_keys`.
+
+Use the `thread_safe_remove_keys` method to remove a list of thread-local keys that were previously added using the `thread_safe_append_keys` method.
+
+=== "thread_safe_remove_keys.py"
+
+    ```python hl_lines="13"
+    --8<-- "examples/logger/src/thread_safe_remove_keys.py"
+    ```
+
+=== "thread_safe_remove_keys_output.json"
+
+    ```json hl_lines="8 9 17 18 26 34"
+    --8<-- "examples/logger/src/thread_safe_remove_keys_output.json"
+    ```
+
+#### Clearing thread-safe additional keys
+
+Use the `thread_safe_clear_keys` method to remove all thread-local keys that were previously added using the `thread_safe_append_keys` method.
+
+=== "thread_safe_clear_keys.py"
+
+    ```python hl_lines="13"
+    --8<-- "examples/logger/src/thread_safe_clear_keys.py"
+    ```
+
+=== "thread_safe_clear_keys_output.json"
+
+    ```json hl_lines="8 9 17 18"
+    --8<-- "examples/logger/src/thread_safe_clear_keys_output.json"
+    ```
+
+#### Accessing thread-safe currently keys
+
+You can view all currently thread-local keys from the Logger state using the `thread_safe_get_current_keys()` method. This method is useful when you need to avoid overwriting keys that are already configured.
+
+=== "thread_safe_get_current_keys.py"
+
+    ```python hl_lines="13"
+    --8<-- "examples/logger/src/thread_safe_get_current_keys.py"
+    ```
+
 ### Reusing Logger across your code
 
 Similar to [Tracer](./tracer.md#reusing-tracer-across-your-code){target="_blank"}, a new instance that uses the same `service` name will reuse a previous Logger instance.

Diff for: examples/logger/src/append_thread_local_keys.py renamed to examples/logger/src/thread_safe_append_keys.py

@@ -8,7 +8,7 @@
 
 
 def threaded_func(order_id: str):
-    logger.append_thread_local_keys(order_id=order_id, thread_id=threading.get_ident())
+    logger.thread_safe_append_keys(order_id=order_id, thread_id=threading.get_ident())
     logger.info("Collecting payment")
 
 

Diff for: examples/logger/src/append_thread_local_keys_output.json renamed to examples/logger/src/thread_safe_append_keys_output.json

@@ -8,9 +8,9 @@
 
 
 def threaded_func(order_id: str):
-    logger.append_thread_local_keys(order_id=order_id, thread_id=threading.get_ident())
+    logger.thread_safe_append_keys(order_id=order_id, thread_id=threading.get_ident())
     logger.info("Collecting payment")
-    logger.clear_thread_local_keys()
+    logger.thread_safe_clear_keys()
     logger.info("Exiting thread")
 
 

Diff for: examples/logger/src/clear_thread_local_keys.py renamed to examples/logger/src/thread_safe_clear_keys.py

@@ -0,0 +1,14 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+@logger.inject_lambda_context
+def lambda_handler(event: dict, context: LambdaContext) -> str:
+    logger.info("Collecting payment")
+
+    if "order" not in logger.thread_safe_get_current_keys():
+        logger.thread_safe_append_keys(order=event.get("order"))
+
+    return "hello world"

Diff for: examples/logger/src/clear_thread_local_keys_output.json renamed to examples/logger/src/thread_safe_clear_keys_output.json

@@ -8,9 +8,9 @@
 
 
 def threaded_func(order_id: str):
-    logger.append_thread_local_keys(order_id=order_id, thread_id=threading.get_ident())
+    logger.thread_safe_append_keys(order_id=order_id, thread_id=threading.get_ident())
     logger.info("Collecting payment")
-    logger.remove_thread_local_keys(["order_id"])
+    logger.thread_safe_remove_keys(["order_id"])
     logger.info("Exiting thread")
 
 

Diff for: examples/logger/src/thread_safe_get_current_keys.py

@@ -97,7 +97,7 @@ def pydanticv2_only():
 def openapi30_schema():
     from urllib.request import urlopen
 
-    f = urlopen("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json")
+    f = urlopen("https://spec.openapis.org/oas/3.0/schema/2021-09-28")
     data = json.loads(f.read().decode("utf-8"))
     return fastjsonschema.compile(
         data,
@@ -109,7 +109,7 @@ def openapi30_schema():
 def openapi31_schema():
     from urllib.request import urlopen
 
-    f = urlopen("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json")
+    f = urlopen("https://spec.openapis.org/oas/3.1/schema/2022-10-07")
     data = json.loads(f.read().decode("utf-8"))
     return fastjsonschema.compile(
         data,