Addressing all feedback

Author: leandrodamascena

docs/lambda-features/durable-functions.md

@@ -14,54 +14,44 @@ description: Using Powertools for AWS Lambda (Python) with Lambda Durable Functi
 | **Durable execution** | Complete lifecycle of a durable function, from start to completion |
 | **Checkpoint**        | Saved state that tracks progress through the workflow              |
 | **Replay**            | Re-execution from the beginning, skipping completed checkpoints    |
-| **Steps**             | Business logic with built-in retries and progress tracking         |
-| **Waits**             | Suspend execution without incurring compute charges                |
+| **Step**              | Business logic with built-in retries and progress tracking         |
+| **Wait**              | Suspend execution without incurring compute charges                |
 
 ## How it works
 
 Durable functions use a **checkpoint/replay mechanism**:
 
-1. Your code runs from the beginning
+1. Your code runs always from the beginning
 2. Completed operations are skipped using stored results
-3. Execution continues from where it left off
+3. Execution of new steps continues from where it left off
 4. State is automatically managed by the SDK
 
 ## Powertools integration
 
-Powertools for AWS Lambda (Python) works seamlessly with Durable Functions. The [Durable Execution SDK](https://github.com/aws/aws-durable-execution-sdk-python){target="_blank" rel="nofollow"} has native integration with Powertools Logger via `context.set_logger()`.
+Powertools for AWS Lambda (Python) works seamlessly with Durable Functions. The [Durable Execution SDK](https://github.com/aws/aws-durable-execution-sdk-python){target="_blank" rel="nofollow"} has native integration with Logger via `context.set_logger()`.
 
 ???+ note "Found an issue?"
-    If you encounter any issues using Powertools for AWS with Durable Functions, please [open an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new?template=bug_report.yml){target="_blank"}.
+    If you encounter any issues using Powertools for AWS Lambda (Python) with Durable Functions, please [open an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new?template=bug_report.yml){target="_blank"}.
 
 ### Logger
 
-The Durable Execution SDK provides a `context.logger` that automatically handles **log deduplication during replays**. You can integrate Powertools Logger to get structured JSON logging while keeping the deduplication benefits.
+The Durable Execution SDK provides a `context.logger` instance that automatically handles **log deduplication during replays**. You can integrate Logger to get structured JSON logging while keeping the deduplication benefits.
 
-#### Using Powertools Logger with context.set_logger
+For the best experience, set the Logger on the durable context. This gives you structured JSON logging with automatic log deduplication during replays:
 
-For the best experience, set the Powertools Logger on the durable context:
-
-```python hl_lines="5 10" title="Integrating Powertools Logger with Durable Functions"
+```python hl_lines="5 11 14 22" title="Integrating Logger with Durable Functions"
 --8<-- "examples/lambda_features/durable_functions/src/using_logger.py"
 ```
 
 This gives you:
 
-- **JSON structured logging** from Powertools for AWS
+- **JSON structured logging** from Powertools for AWS Lambda (Python)
 - **Log deduplication** during replays (logs from completed operations don't repeat)
 - **Automatic SDK enrichment** (execution_arn, parent_id, name, attempt)
 - **Lambda context injection** (request_id, function_name, etc.)
 
-#### Log deduplication during replay
-
-When you use `context.logger`, the SDK prevents duplicate logs during replays:
-
-```python title="Log deduplication behavior"
---8<-- "examples/lambda_features/durable_functions/src/log_deduplication.py"
-```
-
 ???+ warning "Direct logger usage"
-    If you use the Powertools Logger directly (not through `context.logger`), logs will be emitted on every replay:
+    If you use the Logger directly (not through `context.logger`), logs will be emitted on every replay:
 
     ```python
     # Logs will duplicate during replays
@@ -76,23 +66,20 @@ When you use `context.logger`, the SDK prevents duplicate logs during replays:
 Tracer works with Durable Functions. Each execution creates trace segments.
 
 ???+ note "Trace continuity"
-    Due to the replay mechanism, traces may not show a continuous flow. Each execution (including replays) creates separate trace segments. Use the `execution_arn` to correlate traces.
+    Due to the replay mechanism, traces may be interleaved. Each execution (including replays) creates separate trace segments. Use the `execution_arn` to correlate traces.
 
 ```python hl_lines="5 9" title="Using Tracer with Durable Functions"
 --8<-- "examples/lambda_features/durable_functions/src/using_tracer.py"
 ```
 
 ### Metrics
 
-Metrics work with Durable Functions, but be aware that **metrics may be emitted multiple times** during replay if not handled carefully.
+Metrics work with Durable Functions, but be aware that **metrics may be emitted multiple times** during replay if not handled carefully. Emit metrics at workflow completion rather than during intermediate steps to avoid counting replays as new executions.
 
-```python hl_lines="6 10 21" title="Using Metrics with Durable Functions"
---8<-- "examples/lambda_features/durable_functions/src/using_metrics.py"
+```python hl_lines="6 9 18 19 20 21" title="Using Metrics with Durable Functions"
+--8<-- "examples/lambda_features/durable_functions/src/best_practice_metrics.py"
 ```
 
-???+ tip "Accurate metrics"
-    Emit metrics at workflow completion rather than during intermediate steps to avoid counting replays as new executions.
-
 ### Idempotency
 
 The `@idempotent` decorator integrates with Durable Functions and is **replay-aware**. It's useful for protecting the Lambda handler entry point, especially for Event Source Mapping (ESM) invocations like SQS, Kinesis, or DynamoDB Streams.
@@ -111,14 +98,6 @@ The `@idempotent` decorator integrates with Durable Functions and is **replay-aw
 
 - Steps within a durable function are already idempotent via the checkpoint mechanism
 
-### Parser
-
-Parser works with Durable Functions for validating and parsing event payloads.
-
-```python hl_lines="9 14" title="Using Parser with Durable Functions"
---8<-- "examples/lambda_features/durable_functions/src/using_parser.py"
-```
-
 ### Parameters
 
 Parameters work normally with Durable Functions.
@@ -128,26 +107,10 @@ Parameters work normally with Durable Functions.
 ```
 
 ???+ note "Parameter freshness"
-    For long-running workflows (hours/days), parameters fetched at the start may become stale. Consider fetching parameters within steps that need the latest values.
+    If the replay or execution happens within the cache TTL on the same execution environment, the parameter value may come from cache. For long-running workflows (hours/days), parameters fetched at the start may become stale. Consider fetching parameters within steps that need the latest values, and customize the caching behavior with `max_age` to control freshness.
 
 ## Best practices
 
-### Use context.logger for log deduplication
-
-Always use `context.set_logger()` and `context.logger` instead of using the Powertools Logger directly. This ensures logs are deduplicated during replays.
-
-```python title="Recommended logging pattern"
---8<-- "examples/lambda_features/durable_functions/src/best_practice_logging.py"
-```
-
-### Emit metrics at workflow completion
-
-To avoid counting replays as new executions, emit metrics only when the workflow completes successfully.
-
-```python title="Metrics at completion"
---8<-- "examples/lambda_features/durable_functions/src/best_practice_metrics.py"
-```
-
 ### Use Idempotency for ESM triggers
 
 When your durable function is triggered by Event Source Mappings (SQS, Kinesis, DynamoDB Streams), use the `@idempotent` decorator to protect against duplicate invocations.

docs/lambda-features/managed-instances.md

@@ -7,84 +7,52 @@ description: Using Powertools for AWS Lambda (Python) with Lambda Managed Instan
 
 [Lambda Managed Instances](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances.html){target="_blank" rel="nofollow"} enables you to run Lambda functions on Amazon EC2 instances without managing infrastructure. It supports multi-concurrent invocations, EC2 pricing models, and specialized compute options like Graviton4.
 
-## Key differences from Lambda (default)
+## Key differences from Lambda On Demand
 
-| Aspect           | Lambda (default)                            | Lambda Managed Instances                        |
+| Aspect           | Lambda On Demand                            | Lambda Managed Instances                        |
 | ---------------- | ------------------------------------------- | ----------------------------------------------- |
 | **Concurrency**  | Single invocation per execution environment | Multiple concurrent invocations per environment |
 | **Python model** | One process, one request                    | Multiple processes, one request each            |
 | **Pricing**      | Per-request duration                        | EC2-based with Savings Plans support            |
-| **Scaling**      | Scale on demand with cold starts            | Async scaling based on CPU, no cold starts      |
+| **Scaling**      | Scale on demand with cold starts            | Async scaling based on CPU                      |
 | **Isolation**    | Firecracker microVMs                        | Containers on EC2 Nitro                         |
 
 ## How Lambda Python runtime handles concurrency
 
-Unlike Java or Node.js which use threads, the **Lambda Python runtime uses multiple processes** for concurrent requests. Each request runs in a separate process, which provides natural isolation between requests.
+The **Lambda Python runtime uses multiple processes** for concurrent requests. Each request runs in a separate process, which provides natural isolation between requests.
 
 This means:
 
-- **Memory is not shared** between concurrent requests
-- **Global variables** are isolated per process
+- **Each process has its own memory** - global variables are isolated per process
 - **`/tmp` directory is shared** across all processes - use caution with file operations
 
-## Isolation model
-
-Lambda Managed Instances use a different isolation model than Lambda (default):
-
-| Layer                  | Lambda (default)                         | Lambda Managed Instances                   |
-| ---------------------- | ---------------------------------------- | ------------------------------------------ |
-| **Instance level**     | Firecracker microVMs on shared AWS fleet | Containers on EC2 Nitro in your account    |
-| **Security boundary**  | Execution environment                    | Capacity provider                          |
-| **Function isolation** | Strong isolation via microVMs            | Container-based isolation within instances |
-
-**Capacity providers** serve as the security boundary. Functions within the same capacity provider share the underlying EC2 instances. For workloads requiring strong isolation between functions, use separate capacity providers.
-
-For Python specifically, the multi-process model adds another layer of isolation - each concurrent request runs in its own process with separate memory space.
+For more details on the isolation model, see [Lambda Managed Instances documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances.html){target="_blank" rel="nofollow"}.
 
 ## Powertools integration
 
 Powertools for AWS Lambda (Python) works seamlessly with Lambda Managed Instances. All utilities are compatible with the multi-process concurrency model used by Python.
 
-### Logger
-
-Logger works without any changes. Each process has its own logger instance.
-
-```python hl_lines="4 7" title="Using Logger with Managed Instances"
---8<-- "examples/lambda_features/managed_instances/src/using_logger.py"
-```
-
-### Tracer
+### Logger, Tracer, and Metrics
 
-Tracer works without any changes. X-Ray traces are captured per request.
+Core utilities work without any changes. Each process has its own instances, so correlation IDs and traces are naturally isolated per request.
 
 ???+ note "VPC connectivity required"
-    Lambda Managed Instances run in your VPC. Ensure you have [network connectivity](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-networking.html){target="_blank" rel="nofollow"} to send traces to X-Ray.
+    Lambda Managed Instances run in your VPC. Ensure you have [network connectivity](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-networking.html){target="_blank" rel="nofollow"} to send logs to CloudWatch, traces to X-Ray, and metrics to CloudWatch.
 
-```python hl_lines="4 8 12" title="Using Tracer with Managed Instances"
+```python hl_lines="5 6 7 10 11 12 20 25" title="Using Logger, Tracer, and Metrics with Managed Instances"
 --8<-- "examples/lambda_features/managed_instances/src/using_tracer.py"
 ```
 
-### Metrics
-
-Metrics work without any changes. Each process flushes metrics independently.
-
-???+ note "VPC connectivity required"
-    Ensure you have [network connectivity](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-networking.html){target="_blank" rel="nofollow"} to send metrics to CloudWatch.
-
-```python hl_lines="5 9 12" title="Using Metrics with Managed Instances"
---8<-- "examples/lambda_features/managed_instances/src/using_metrics.py"
-```
-
 ### Parameters
 
-Parameters utility works correctly, but be aware that **cache is per-process**.
+Parameters utility works as expected, but be aware that **caching is per-process**.
 
 ```python hl_lines="9" title="Using Parameters with Managed Instances"
 --8<-- "examples/lambda_features/managed_instances/src/using_parameters.py"
 ```
 
 ???+ tip "Cache behavior"
-    Since each process has its own cache, you might see more calls to SSM/Secrets Manager during initial warm-up. Once each process has cached the value, subsequent requests within that process use the cache.
+    Since each process has its own cache, you might see more calls to SSM/Secrets Manager during initial warm-up. Once each process has cached the value, subsequent requests within that process use the cache. You can customize the caching behavior with `max_age` to control the TTL.
 
 ### Idempotency
 
@@ -94,35 +62,6 @@ Idempotency works without any changes. It uses DynamoDB for state management, wh
 --8<-- "examples/lambda_features/managed_instances/src/using_idempotency.py"
 ```
 
-### Batch Processing
-
-Batch Processing works without any changes. Each batch is processed within a single process.
-
-```python hl_lines="5 8 14" title="Using Batch Processing with Managed Instances"
---8<-- "examples/lambda_features/managed_instances/src/using_batch.py"
-```
-
-???+ note "Other utilities"
-    All other Powertools for AWS utilities (Feature Flags, Validation, Parser, Data Masking, etc.) work without any changes. If you encounter any issues, please [open an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new?template=bug_report.yml){target="_blank"}.
-
-## Working with shared resources
-
-### The `/tmp` directory
-
-The `/tmp` directory is **shared across all processes** in the execution environment. Use caution when writing files.
-
-```python title="Safe file handling with unique names"
---8<-- "examples/lambda_features/managed_instances/src/tmp_file_handling.py"
-```
-
-### Database connections
-
-Since each process is independent, connection pooling behaves differently than in threaded runtimes.
-
-```python title="Database connections per process"
---8<-- "examples/lambda_features/managed_instances/src/database_connections.py"
-```
-
 ## VPC connectivity
 
 Lambda Managed Instances require VPC configuration for:
@@ -136,18 +75,19 @@ Configure connectivity using one of these options:
 1. **VPC Endpoints** - Private connectivity without internet access
 2. **NAT Gateway** - Internet access from private subnets
 3. **Public subnet with Internet Gateway** - Direct internet access
+4. **Egress-only Internet Gateway** - IPv6 outbound connectivity without inbound access ([learn more](https://docs.aws.amazon.com/vpc/latest/userguide/egress-only-internet-gateway.html){target="_blank" rel="nofollow"})
 
 See [Networking for Lambda Managed Instances](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-networking.html){target="_blank" rel="nofollow"} for detailed setup instructions.
 
 ## FAQ
 
 ### Does Powertools for AWS Lambda (Python) work with Lambda Managed Instances?
 
-Yes, all Powertools for AWS utilities work seamlessly with Lambda Managed Instances. The multi-process model in Python provides natural isolation between concurrent requests.
+Yes, all Powertools for AWS Lambda (Python) utilities work seamlessly with Lambda Managed Instances. The multi-process model in Python provides natural isolation between concurrent requests.
 
 ### Is my code thread-safe?
 
-For Python, you don't need to worry about thread safety because Lambda Managed Instances uses **multiple processes**, not threads. Each request runs in its own process with isolated memory.
+Lambda Managed Instances uses **multiple processes**, instead of threads. Each request runs in its own process with isolated memory. If you implement multi-threading within your handler, you are responsible for thread safety.
 
 ### Why is my cache not shared between requests?
 
@@ -157,10 +97,6 @@ Each process maintains its own cache (for Parameters, Feature Flags, etc.). This
 
 Yes, but remember they are **per-process**, not shared across concurrent requests. This is actually safer than shared state.
 
-### How should I handle files in `/tmp`?
-
-Use unique file names (include request ID or UUID) to avoid conflicts between concurrent requests. Always clean up files after use to avoid filling the shared `/tmp` directory.
-
-### Do I need to change my existing Powertools for AWS code?
+### Do I need to change my existing Powertools for AWS Lambda (Python) code?
 
-No changes are required. Your existing code will work as-is with Lambda Managed Instances.
+No changes are required if you are running Powertools for AWS Lambda (Python) version **3.4.0** or later. Your existing code will work as-is with Lambda Managed Instances.

examples/lambda_features/durable_functions/src/best_practice_logging.py

@@ -14,6 +14,10 @@ def handler(event: dict, context: DurableContext) -> str:
         name="process",
     )
 
-    # Emit only at the end
-    metrics.add_metric(name="WorkflowCompleted", unit=MetricUnit.Count, value=1)
+    # Emit metrics in a dedicated step to ensure they are only counted once
+    context.step(
+        lambda _: metrics.add_metric(name="WorkflowCompleted", unit=MetricUnit.Count, value=1),
+        name="emit_completion_metric",
+    )
+
     return result