Adding build recipes section

Author: leandrodamascena

docs/build_recipes.md

@@ -358,10 +358,10 @@ Optimized approach using Lambda Layers to separate dependencies from application
     --8<-- "examples/build_recipes/sam/with-layers/layers/dependencies/requirements.txt"
     ```
 
-=== "src/api/app_sam_layer.py"
+=== "src/app/app_sam_layer.py"
 
     ```python
-    --8<-- "examples/build_recipes/sam/with-layers/src/api/app_sam_layer.py"
+    --8<-- "examples/build_recipes/sam/with-layers/src/app/app_sam_layer.py"
     ```
 
 === "src/worker/worker_sam_layer.py"
@@ -463,10 +463,10 @@ Multi-environment CDK setup with separate stacks, DynamoDB integration, and SQS
     --8<-- "examples/build_recipes/cdk/multi-stack/app_multi_stack.py"
     ```
 
-=== "src/api/api.py"
+=== "src/app/api.py"
 
     ```python
-    --8<-- "examples/build_recipes/cdk/multi-stack/src/api/api.py"
+    --8<-- "examples/build_recipes/cdk/multi-stack/src/app/api.py"
     ```
 
 === "src/worker/worker.py"
@@ -521,10 +521,10 @@ Pants excels at managing complex projects with multiple Lambda functions that sh
     --8<-- "examples/build_recipes/pants/multi-target/BUILD"
     ```
 
-=== "api/handler.py"
+=== "app/handler.py"
 
     ```python
-    --8<-- "examples/build_recipes/pants/multi-target/api/handler.py"
+    --8<-- "examples/build_recipes/pants/multi-target/app/handler.py"
     ```
 
 === "worker/workder_pants.py"

examples/build_recipes/cdk/multi-stack/src/app/__init__.py

@@ -0,0 +1,49 @@
+import os
+
+import boto3
+
+from aws_lambda_powertools import Logger, Metrics, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.metrics import MetricUnit
+
+logger = Logger()
+tracer = Tracer()
+metrics = Metrics()
+app = APIGatewayRestResolver()
+
+# Initialize AWS clients
+dynamodb = boto3.resource("dynamodb")
+sqs = boto3.client("sqs")
+
+table = dynamodb.Table(os.environ["TABLE_NAME"])
+queue_url = os.environ["QUEUE_URL"]
+
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy", "service": "powertools-cdk-api"}
+
+
+@app.post("/tasks")
+@tracer.capture_method
+def create_task():
+    task_data = app.current_event.json_body
+
+    # Store in DynamoDB
+    table.put_item(Item={"pk": task_data["task_id"], "task_type": task_data["task_type"], "status": "pending"})
+
+    # Send to SQS for processing
+    sqs.send_message(QueueUrl=queue_url, MessageBody=app.current_event.body)
+
+    metrics.add_metric(name="TaskCreated", unit=MetricUnit.Count, value=1)
+    logger.info("Task created", extra={"task_id": task_data["task_id"]})
+
+    return {"message": "Task created successfully", "task_id": task_data["task_id"]}
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+@metrics.log_metrics(capture_cold_start_metric=True)
+def lambda_handler(event, context):
+    return app.resolve(event, context)

examples/build_recipes/cdk/multi-stack/src/app/api.py

@@ -73,14 +73,14 @@ def _create_api_function(self) -> _lambda.Function:
             self,
             "ApiFunction",
             runtime=_lambda.Runtime.PYTHON_3_13,
-            handler="api.lambda_handler",
-            code=_lambda.Code.from_asset("src/api"),
+            handler="app.lambda_handler",
+            code=_lambda.Code.from_asset("src/app"),
             layers=[self.powertools_layer],
             timeout=Duration.seconds(30),
             memory_size=512 if self.env == "prod" else 256,
             environment={
                 "ENVIRONMENT": self.env,
-                "POWERTOOLS_SERVICE_NAME": f"api-{self.env}",
+                "POWERTOOLS_SERVICE_NAME": f"app-{self.env}",
                 "POWERTOOLS_METRICS_NAMESPACE": f"MyApp/{self.env}",
                 "POWERTOOLS_LOG_LEVEL": "INFO" if self.env == "prod" else "DEBUG",
                 "TABLE_NAME": self.table.table_name,

examples/build_recipes/cdk/multi-stack/stacks/powertools_cdk_stack.py

@@ -0,0 +1,35 @@
+from aws_lambda_powertools import Logger, Metrics, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.metrics import MetricUnit
+
+logger = Logger()
+tracer = Tracer()
+metrics = Metrics()
+app = APIGatewayRestResolver()
+
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy", "service": "powertools-pants-api"}
+
+
+@app.get("/metrics")
+def get_metrics():
+    metrics.add_metric(name="MetricsEndpointCalled", unit=MetricUnit.Count, value=1)
+    return {"message": "Metrics recorded"}
+
+
+@app.post("/tasks")
+def create_task():
+    task_data = app.current_event.json_body
+    logger.info("Task created", extra={"task": task_data})
+    metrics.add_metric(name="TaskCreated", unit=MetricUnit.Count, value=1)
+    return {"message": "Task created successfully", "task_id": task_data.get("id")}
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+@metrics.log_metrics(capture_cold_start_metric=True)
+def lambda_handler(event, context):
+    return app.resolve(event, context)

examples/build_recipes/pants/multi-target/app/handler.py

@@ -0,0 +1,50 @@
+from typing import Optional
+
+import requests
+from pydantic import BaseModel
+
+from aws_lambda_powertools import Logger, Metrics, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.metrics import MetricUnit
+
+logger = Logger()
+tracer = Tracer()
+metrics = Metrics()
+app = APIGatewayRestResolver()
+
+
+class UserModel(BaseModel):
+    name: str
+    email: str
+    age: Optional[int] = None
+
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy", "service": "powertools-sam-layers"}
+
+
+@app.post("/users")
+def create_user(user: UserModel):
+    logger.info("Creating user", extra={"user": user.model_dump()})
+    metrics.add_metric(name="UserCreated", unit=MetricUnit.Count, value=1)
+    return {"message": f"User {user.name} created successfully"}
+
+
+@app.get("/external")
+@tracer.capture_method
+def fetch_external_data():
+    """Example using requests from dependencies layer"""
+    response = requests.get("https://httpbin.org/json")
+    data = response.json()
+
+    metrics.add_metric(name="ExternalApiCalled", unit=MetricUnit.Count, value=1)
+    return {"external_data": data}
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+@metrics.log_metrics(capture_cold_start_metric=True)
+def lambda_handler(event, context):
+    return app.resolve(event, context)

examples/build_recipes/sam/with-layers/src/app/app_sam_layer.py

@@ -28,7 +28,7 @@ Resources:
   ApiFunction:
     Type: AWS::Serverless::Function
     Properties:
-      CodeUri: src/api/
+      CodeUri: src/app/
       Handler: app_sam_layer.lambda_handler
       Layers:
         - arn:aws:lambda:us-east-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:21