docs: adding new Lambda features

Author: leandrodamascena

docs/lambda-features/durable-functions.md

@@ -0,0 +1,185 @@
+---
+title: Durable Functions
+description: Using Powertools for AWS Lambda (Python) with Lambda Durable Functions
+---
+
+<!-- markdownlint-disable MD043 -->
+
+[Lambda Durable Functions](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html){target="_blank" rel="nofollow"} enable you to build resilient multi-step workflows that can execute for up to one year. They use checkpoints to track progress and automatically recover from failures through replay.
+
+## Key concepts
+
+| Concept               | Description                                                        |
+| --------------------- | ------------------------------------------------------------------ |
+| **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                |
+
+## How it works
+
+Durable functions use a **checkpoint/replay mechanism**:
+
+1. Your code runs from the beginning
+2. Completed operations are skipped using stored results
+3. Execution 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()`.
+
+???+ 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"}.
+
+### 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.
+
+#### Using Powertools Logger with context.set_logger
+
+For the best experience, set the Powertools Logger on the durable context:
+
+```python hl_lines="5 10" title="Integrating Powertools Logger with Durable Functions"
+--8<-- "examples/lambda_features/durable_functions/src/using_logger.py"
+```
+
+This gives you:
+
+- **JSON structured logging** from Powertools for AWS
+- **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:
+
+    ```python
+    # Logs will duplicate during replays
+    logger.info("This appears on every replay")
+
+    # Use context.logger instead for deduplication
+    context.logger.info("This appears only once")
+    ```
+
+### Tracer
+
+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.
+
+```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.
+
+```python hl_lines="6 10 21" title="Using Metrics with Durable Functions"
+--8<-- "examples/lambda_features/durable_functions/src/using_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.
+
+```python hl_lines="9 15" title="Using Idempotency with Durable Functions"
+--8<-- "examples/lambda_features/durable_functions/src/using_idempotency.py"
+```
+
+**When to use Powertools Idempotency:**
+
+- Protecting the Lambda handler entry point from duplicate invocations
+- Methods you don't want to convert into steps but need idempotency guarantees
+- Event Source Mapping triggers (SQS, Kinesis, DynamoDB Streams)
+
+**When you don't need it:**
+
+- 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.
+
+```python hl_lines="13" title="Using Parameters with Durable Functions"
+--8<-- "examples/lambda_features/durable_functions/src/using_parameters.py"
+```
+
+???+ 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.
+
+## 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.
+
+```python title="Idempotency for ESM"
+--8<-- "examples/lambda_features/durable_functions/src/best_practice_idempotency.py"
+```
+
+## FAQ
+
+### Do I need Idempotency utility with Durable Functions?
+
+It depends on your use case. Steps within a durable function are already idempotent via checkpoints. However, the `@idempotent` decorator is useful for protecting the Lambda handler entry point, especially for Event Source Mapping invocations (SQS, Kinesis, DynamoDB Streams) where the same event might trigger multiple invocations.
+
+### Why do I see duplicate logs?
+
+If you're using the logger directly instead of `context.logger`, logs will be emitted on every replay. Use `context.set_logger(logger)` and then `context.logger.info()` to get automatic log deduplication.
+
+### How do I correlate logs across replays?
+
+Use the `execution_arn` field that's automatically added to every log entry when using `context.logger`:
+
+```sql
+fields @timestamp, @message, execution_arn
+| filter execution_arn = "arn:aws:lambda:us-east-1:123456789012:function:my-function:execution-id"
+| sort @timestamp asc
+```
+
+### Can I use Tracer with Durable Functions?
+
+Yes, but be aware that each execution (including replays) creates separate trace segments. Use the `execution_arn` as a correlation identifier for end-to-end visibility.
+
+### How should I emit metrics without duplicates?
+
+Emit metrics at workflow completion rather than during intermediate steps. This ensures you count completed workflows, not replay attempts.

docs/lambda-features/index.md

@@ -0,0 +1,28 @@
+---
+title: Lambda Features
+description: Using Powertools with advanced Lambda features
+---
+
+<!-- markdownlint-disable MD043 -->
+
+This section covers how to use Powertools for AWS Lambda (Python) with advanced Lambda features like Lambda Managed Instances and Durable Functions.
+
+<div class="grid cards" markdown>
+
+- :material-server:{ .lg .middle } __Lambda Managed Instances__
+
+    ---
+
+    Run Lambda functions on EC2 instances with multi-concurrent invocations
+
+    [:octicons-arrow-right-24: Getting started](./managed-instances.md)
+
+- :material-state-machine:{ .lg .middle } __Durable Functions__
+
+    ---
+
+    Build resilient multi-step workflows that can execute for up to one year
+
+    [:octicons-arrow-right-24: Getting started](./durable-functions.md)
+
+</div>

docs/lambda-features/managed-instances.md

@@ -0,0 +1,166 @@
+---
+title: Lambda Managed Instances
+description: Using Powertools for AWS Lambda (Python) with Lambda Managed Instances
+---
+
+<!-- markdownlint-disable MD043 -->
+
+[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)
+
+| Aspect           | Lambda (default)                            | 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      |
+| **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.
+
+This means:
+
+- **Memory is not shared** between concurrent requests
+- **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.
+
+## 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
+
+Tracer works without any changes. X-Ray traces are captured 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.
+
+```python hl_lines="4 8 12" title="Using Tracer 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**.
+
+```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.
+
+### Idempotency
+
+Idempotency works without any changes. It uses DynamoDB for state management, which is external to the process.
+
+```python hl_lines="7 10" title="Using Idempotency with Managed Instances"
+--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:
+
+- Sending logs to CloudWatch Logs
+- Sending traces to X-Ray
+- Accessing AWS services (SSM, Secrets Manager, DynamoDB, etc.)
+
+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
+
+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.
+
+### 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.
+
+### Why is my cache not shared between requests?
+
+Each process maintains its own cache (for Parameters, Feature Flags, etc.). This is expected behavior. The cache will warm up independently per process, which may result in slightly more calls to backend services during initial warm-up.
+
+### Can I use global variables?
+
+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?
+
+No changes are required. Your existing code will work as-is with Lambda Managed Instances.