Merge branch 'develop' into ci/enable-sar

leandrodamascena · web-flow · commit 2f3c0451071a · 2025-02-27T18:36:00.000Z
diff --git a/.github/workflows/layer_govcloud.yml b/.github/workflows/layer_govcloud.yml
@@ -104,11 +104,11 @@ jobs:
     environment: GovCloud ${{ inputs.environment }} (East)
     steps:
       - name: Download Zip
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.zip
       - name: Download Metadata
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.json
       - name: Verify Layer Signature
@@ -173,11 +173,11 @@ jobs:
       name: GovCloud ${{ inputs.environment }} (West)
     steps:
       - name: Download Zip
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.zip
       - name: Download Metadata
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.json
       - name: Verify Layer Signature
diff --git a/.github/workflows/layer_govcloud_python313.yml b/.github/workflows/layer_govcloud_python313.yml
@@ -96,11 +96,11 @@ jobs:
     environment: GovCloud ${{ inputs.environment }} (East)
     steps:
       - name: Download Zip
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.zip
       - name: Download Metadata
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.json
       - name: Verify Layer Signature
@@ -161,11 +161,11 @@ jobs:
       name: GovCloud ${{ inputs.environment }} (West)
     steps:
       - name: Download Zip
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.zip
       - name: Download Metadata
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ matrix.layer }}_${{ matrix.arch }}.json
       - name: Verify Layer Signature
diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml
@@ -255,7 +255,7 @@ jobs:
           artifact_name: ${{ needs.seal.outputs.artifact_name }}
 
       - name: Download provenance
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{needs.provenance.outputs.provenance-name}}
 
diff --git a/.github/workflows/publish_v2_layer.yml b/.github/workflows/publish_v2_layer.yml
@@ -117,14 +117,14 @@ jobs:
           pip install --require-hashes -r requirements.txt
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@4574d27a4764455b42196d70a065bc6853246a25 # v2.0.0
+        uses: docker/setup-qemu-action@5964de0df58d5ad28b04d8fe2e6b80ad47105b91 # v2.0.0
         with:
           platforms: arm64
         # NOTE: we need QEMU to build Layer against a different architecture (e.g., ARM)
 
       - name: Set up Docker Buildx
         id: builder
-        uses: docker/setup-buildx-action@f7ce87c1d6bead3e36075b2ce75da1f6cc28aaca # v3.9.0
+        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0
         with:
           install: true
           driver: docker
@@ -258,7 +258,7 @@ jobs:
           artifact_name: ${{ inputs.source_code_artifact_name }}
 
       - name: Download CDK layer artifacts
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           path: cdk-layer-stack
           pattern: cdk-layer-stack-*  # merge all Layer artifacts created per region earlier (reusable_deploy_v2_layer_stack.yml; step "Save Layer ARN artifact")
diff --git a/.github/workflows/publish_v3_layer.yml b/.github/workflows/publish_v3_layer.yml
@@ -139,14 +139,14 @@ jobs:
           pip install --require-hashes -r requirements.txt
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@4574d27a4764455b42196d70a065bc6853246a25 # v2.0.0
+        uses: docker/setup-qemu-action@5964de0df58d5ad28b04d8fe2e6b80ad47105b91 # v2.0.0
         with:
           platforms: arm64
         # NOTE: we need QEMU to build Layer against a different architecture (e.g., ARM)
 
       - name: Set up Docker Buildx
         id: builder
-        uses: docker/setup-buildx-action@f7ce87c1d6bead3e36075b2ce75da1f6cc28aaca # v3.9.0
+        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0
         with:
           install: true
           driver: docker
diff --git a/.github/workflows/quality_code_cdk_constructor.yml b/.github/workflows/quality_code_cdk_constructor.yml
@@ -51,13 +51,13 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: "poetry"
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@4574d27a4764455b42196d70a065bc6853246a25 # v2.0.0
+        uses: docker/setup-qemu-action@5964de0df58d5ad28b04d8fe2e6b80ad47105b91 # v2.0.0
         with:
           platforms: arm64
         # NOTE: we need QEMU to build Layer against a different architecture (e.g., ARM)
       - name: Set up Docker Buildx
         id: builder
-        uses: docker/setup-buildx-action@f7ce87c1d6bead3e36075b2ce75da1f6cc28aaca # v3.9.0
+        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0
         with:
           install: true
           driver: docker
diff --git a/.github/workflows/reusable_deploy_v2_layer_stack.yml b/.github/workflows/reusable_deploy_v2_layer_stack.yml
@@ -181,7 +181,7 @@ jobs:
       - name: install deps
         run: poetry install
       - name: Download artifact
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ inputs.artefact-name }}
           path: layer
diff --git a/.github/workflows/reusable_deploy_v2_sar.yml b/.github/workflows/reusable_deploy_v2_sar.yml
@@ -117,7 +117,7 @@ jobs:
         with:
           node-version: ${{ env.NODE_VERSION }}
       - name: Download artifact
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: ${{ inputs.artefact-name }}
       - name: Unzip artefact
diff --git a/.github/workflows/reusable_deploy_v3_layer_stack.yml b/.github/workflows/reusable_deploy_v3_layer_stack.yml
@@ -189,7 +189,7 @@ jobs:
       - name: install deps
         run: poetry install
       - name: Download artifact
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: cdk-layer-artifact-py${{ matrix.python-version }}
           path: layer_v3
diff --git a/.github/workflows/reusable_deploy_v3_sar.yml b/.github/workflows/reusable_deploy_v3_sar.yml
@@ -113,7 +113,7 @@ jobs:
         with:
           node-version: ${{ env.NODE_VERSION }}
       - name: Download artifact
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
         with:
           name: cdk-layer-artifact-py${{ matrix.python-version }}
       - name: Unzip artefact
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,13 +4,25 @@
 <a name="unreleased"></a>
 # Unreleased
 
+## Features
+
+* **logger:** add new logic to sample debug logs ([#6142](https://github.com/aws-powertools/powertools-lambda-python/issues/6142))
+
 ## Maintenance
 
 * **ci:** new pre-release 3.7.1a0 ([#6166](https://github.com/aws-powertools/powertools-lambda-python/issues/6166))
+* **ci:** new pre-release 3.7.1a1 ([#6178](https://github.com/aws-powertools/powertools-lambda-python/issues/6178))
+* **deps:** bump actions/download-artifact from 4.1.8 to 4.1.9 ([#6174](https://github.com/aws-powertools/powertools-lambda-python/issues/6174))
+* **deps:** bump docker/setup-qemu-action from 3.4.0 to 3.5.0 ([#6176](https://github.com/aws-powertools/powertools-lambda-python/issues/6176))
+* **deps:** bump docker/setup-buildx-action from 3.9.0 to 3.10.0 ([#6175](https://github.com/aws-powertools/powertools-lambda-python/issues/6175))
+* **deps-dev:** bump aws-cdk from 2.1000.3 to 2.1001.0 ([#6173](https://github.com/aws-powertools/powertools-lambda-python/issues/6173))
+* **deps-dev:** bump cfn-lint from 1.26.0 to 1.26.1 ([#6169](https://github.com/aws-powertools/powertools-lambda-python/issues/6169))
+* **deps-dev:** bump aws-cdk-aws-lambda-python-alpha from 2.180.0a0 to 2.181.0a0 ([#6172](https://github.com/aws-powertools/powertools-lambda-python/issues/6172))
 * **deps-dev:** bump cfn-lint from 1.25.1 to 1.26.0 ([#6164](https://github.com/aws-powertools/powertools-lambda-python/issues/6164))
 * **deps-dev:** bump boto3-stubs from 1.36.26 to 1.37.0 ([#6165](https://github.com/aws-powertools/powertools-lambda-python/issues/6165))
 * **deps-dev:** bump mypy-boto3-appconfigdata from 1.36.0 to 1.37.0 in the boto-typing group ([#6163](https://github.com/aws-powertools/powertools-lambda-python/issues/6163))
 * **deps-dev:** bump aws-cdk from 2.1000.2 to 2.1000.3 ([#6162](https://github.com/aws-powertools/powertools-lambda-python/issues/6162))
+* **deps-dev:** bump boto3-stubs from 1.37.0 to 1.37.1 ([#6170](https://github.com/aws-powertools/powertools-lambda-python/issues/6170))
 
 
 <a name="v3.7.0"></a>
diff --git a/aws_lambda_powertools/logging/logger.py b/aws_lambda_powertools/logging/logger.py
@@ -220,6 +220,10 @@ def __init__(
         serialize_stacktrace: bool = True,
         **kwargs,
     ) -> None:
+
+        # Used in case of sampling
+        self.initial_log_level = self._determine_log_level(level)
+
         self.service = resolve_env_var_choice(
             choice=service,
             env=os.getenv(constants.SERVICE_NAME_ENV, "service_undefined"),
@@ -339,6 +343,17 @@ def _init_logger(
         self._logger.init = True  # type: ignore[attr-defined]
         self._logger.powertools_handler = self.logger_handler  # type: ignore[attr-defined]
 
+    def refresh_sample_rate_calculation(self) -> None:
+        """
+        Refreshes the sample rate calculation by reconfiguring logging settings.
+
+        Returns
+        -------
+            None
+        """
+        self._logger.setLevel(self.initial_log_level)
+        self._configure_sampling()
+
     def _configure_sampling(self) -> None:
         """Dynamically set log level based on sampling rate
 
@@ -347,15 +362,20 @@ def _configure_sampling(self) -> None:
         InvalidLoggerSamplingRateError
             When sampling rate provided is not a float
         """
+        if not self.sampling_rate:
+            return
+
         try:
-            if self.sampling_rate and random.random() <= float(self.sampling_rate):
-                logger.debug("Setting log level to Debug due to sampling rate")
+            # This is not testing < 0 or > 1 conditions
+            # Because I don't need other if condition here
+            if random.random() <= float(self.sampling_rate):
                 self._logger.setLevel(logging.DEBUG)
+                logger.debug("Setting log level to DEBUG due to sampling rate")
         except ValueError:
             raise InvalidLoggerSamplingRateError(
                 (
                     f"Expected a float value ranging 0 to 1, but received {self.sampling_rate} instead."
-                    "Please review POWERTOOLS_LOGGER_SAMPLE_RATE environment variable."
+                    "Please review POWERTOOLS_LOGGER_SAMPLE_RATE environment variable or `sampling_rate` parameter."
                 ),
             )
 
@@ -465,6 +485,12 @@ def decorate(event, context, *args, **kwargs):
                 logger.debug("Event received")
                 self.info(extract_event_from_common_models(event))
 
+            # Sampling rate is defined, and this is not ColdStart
+            # then we need to recalculate the sampling
+            # See: https://github.com/aws-powertools/powertools-lambda-python/issues/6141
+            if self.sampling_rate and not cold_start:
+                self.refresh_sample_rate_calculation()
+
             return lambda_handler(event, context, *args, **kwargs)
 
         return decorate
diff --git a/aws_lambda_powertools/shared/version.py b/aws_lambda_powertools/shared/version.py
@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.7.1a0"
+VERSION = "3.7.1a1"
diff --git a/docs/core/logger.md b/docs/core/logger.md
@@ -627,24 +627,27 @@ Notice in the CloudWatch Logs output how `payment_id` appears as expected when l
 
 ### Sampling debug logs
 
-Use sampling when you want to dynamically change your log level to **DEBUG** based on a **percentage of your concurrent/cold start invocations**.
+Use sampling when you want to dynamically change your log level to **DEBUG** based on a **percentage of the Lambda function invocations**.
 
-You can use values ranging from `0.0` to `1` (100%) when setting `POWERTOOLS_LOGGER_SAMPLE_RATE` env var, or `sample_rate` parameter in Logger.
+You can use values ranging from `0.0` to `1` (100%) when setting `POWERTOOLS_LOGGER_SAMPLE_RATE` env var, or `sampling_rate` parameter in Logger.
 
 ???+ tip "Tip: When is this useful?"
-    Let's imagine a sudden spike increase in concurrency triggered a transient issue downstream. When looking into the logs you might not have enough information, and while you can adjust log levels it might not happen again.
+    Log sampling allows you to capture debug information for a fraction of your requests, helping you diagnose rare or intermittent issues without increasing the overall verbosity of your logs.
 
-    This feature takes into account transient issues where additional debugging information can be useful.
+    Example: Imagine an e-commerce checkout process where you want to understand rare payment gateway errors. With 10% sampling, you'll log detailed information for a small subset of transactions, making troubleshooting easier without generating excessive logs.
 
-Sampling decision happens at the Logger initialization. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
+The sampling decision happens automatically with each invocation when using `@logger.inject_lambda_context` decorator.  When not using the decorator, you're in charge of refreshing it via `refresh_sample_rate_calculation` method. Skipping both may lead to unexpected sampling results.
 
-???+ note
-	Open a [feature request](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2C+triage&template=feature_request.md&title=){target="_blank"} if you want Logger to calculate sampling for every invocation
+=== "sampling_debug_logs_with_decorator.py"
 
-=== "sampling_debug_logs.py"
+    ```python hl_lines="5 8"
+    --8<-- "examples/logger/src/sampling_debug_logs_with_decorator.py"
+    ```
 
-    ```python hl_lines="6 10"
-    --8<-- "examples/logger/src/sampling_debug_logs.py"
+=== "sampling_debug_logs_with_standalone_function.py"
+
+    ```python hl_lines="5 12"
+    --8<-- "examples/logger/src/sampling_debug_logs_with_standalone_function.py"
     ```
 
 === "sampling_debug_logs_output.json"
diff --git a/examples/logger/src/sampling_debug_logs_with_decorator.py b/examples/logger/src/sampling_debug_logs_with_decorator.py
@@ -2,10 +2,10 @@
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
 # Sample 10% of debug logs e.g. 0.1
-# NOTE: this evaluation will only occur at cold start
 logger = Logger(service="payment", sample_rate=0.1)
 
 
+@logger.inject_lambda_context
 def lambda_handler(event: dict, context: LambdaContext):
     logger.debug("Verifying whether order_id is present")
     logger.info("Collecting payment")
diff --git a/examples/logger/src/sampling_debug_logs_with_standalone_function.py b/examples/logger/src/sampling_debug_logs_with_standalone_function.py
@@ -0,0 +1,14 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+# Sample 10% of debug logs e.g. 0.1
+logger = Logger(service="payment", sample_rate=0.1)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    logger.debug("Verifying whether order_id is present")
+    logger.info("Collecting payment")
+
+    logger.refresh_sample_rate_calculation()
+
+    return "hello world"
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "aws-lambda-powertools-python-e2e",
   "version": "1.0.0",
   "devDependencies": {
-    "aws-cdk": "^2.1000.3"
+    "aws-cdk": "^2.1001.0"
   },
   "dependencies": {
     "package-lock.json": "^1.0.0"
diff --git a/poetry.lock b/poetry.lock
diff --git a/provenance/3.7.1a1/multiple.intoto.jsonl b/provenance/3.7.1a1/multiple.intoto.jsonl
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tests/functional/logger/required_dependencies/test_logger.py b/tests/functional/logger/required_dependencies/test_logger.py
