Skip to content

Tutorial

This tutorial progressively introduces Powertools for AWS Lambda (Python) core utilities by using one feature at a time.

Requirements

Getting started

Let's clone our sample project before we add one feature at a time.

Tip: Want to skip to the final project?

Bootstrap directly via SAM CLI:

1
sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.14 --no-tracing
Use SAM CLI to initialize the sample project
1
sam init --runtime python3.14 --dependency-manager pip --app-template hello-world --name powertools-quickstart

Project structure

As we move forward, we will modify the following files within the powertools-quickstart folder:

  • app.py - Application code.
  • template.yaml - AWS infrastructure configuration using SAM.
  • requirements.txt - List of extra Python packages needed.

Code example

Let's configure our base application to look like the following code snippet.

1
2
3
4
5
6
7
8
9
import json


def hello():
    return {"statusCode": 200, "body": json.dumps({"message": "hello unknown!"})}


def lambda_handler(event, context):
    return hello()
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Sample SAM Template for powertools-quickstart
Globals:
    Function:
        Timeout: 3
Resources:
    HelloWorldFunction:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: hello_world/
            Handler: app.lambda_handler
            Runtime: python3.13
            Architectures:
                - x86_64
            Events:
                HelloWorld:
                    Type: Api
                    Properties:
                        Path: /hello
                        Method: get
Outputs:
    HelloWorldApi:
        Description: "API Gateway endpoint URL for Prod stage for Hello World function"
        Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/"

Our Lambda code consists of an entry point function named lambda_handler, and a hello function.

When API Gateway receives a HTTP GET request on /hello route, Lambda will call our lambda_handler function, subsequently calling the hello function. API Gateway will use this response to return the correct HTTP Status Code and payload back to the caller.

Warning

For simplicity, we do not set up authentication and authorization! You can find more information on how to implement it on AWS SAM documentation.

Run your code

At each point, you have two ways to run your code: locally and within your AWS account.

Local test

AWS SAM allows you to execute a serverless application locally by running sam build && sam local start-api in your preferred shell.

Build and run API Gateway locally
1
2
3
> sam build && sam local start-api
...
2021-11-26 17:43:08  * Running on http://127.0.0.1:3000/ (Press CTRL+C to quit)

As a result, a local API endpoint will be exposed and you can invoke it using your browser, or your preferred HTTP API client e.g., Postman, httpie, etc.

Invoking our function locally via curl
1
2
> curl http://127.0.0.1:3000/hello
{"message": "hello unknown!"}
Info

To learn more about local testing, please visit the AWS SAM CLI local testing documentation.

Live test

First, you need to deploy your application into your AWS Account by issuing sam build && sam deploy --guided command. This command builds a ZIP package of your source code, and deploy it to your AWS Account.

Build and deploy your serverless application
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
> sam build && sam deploy --guided
...
CloudFormation outputs from deployed stack
------------------------------------------------------------------------------------------------------------------------------------------
Outputs
------------------------------------------------------------------------------------------------------------------------------------------
Key                 HelloWorldFunctionIamRole
Description         Implicit IAM Role created for Hello World function
Value               arn:aws:iam::123456789012:role/sam-app-HelloWorldFunctionRole-1T2W3H9LZHGGV

Key                 HelloWorldApi
Description         API Gateway endpoint URL for Prod stage for Hello World function
Value               https://1234567890.execute-api.eu-central-1.amazonaws.com/Prod/hello/

Key                 HelloWorldFunction
Description         Hello World Lambda Function ARN
Value               arn:aws:lambda:eu-central-1:123456789012:function:sam-app-HelloWorldFunction-dOcfAtYoEiGo
------------------------------------------------------------------------------------------------------------------------------------------
Successfully created/updated stack - sam-app in eu-central-1

At the end of the deployment, you will find the API endpoint URL within Outputs section. You can use this URL to test your serverless application.

Invoking our application via API endpoint
1
2
> curl https://1234567890.execute-api.eu-central-1.amazonaws.com/Prod/hello
{"message": "hello unknown!"}%
Info

For more details on AWS SAM deployment mechanism, see SAM Deploy reference docs.

Routing

Adding a new route

Let's expand our application with a new route - /hello/{name}. It will accept an username as a path input and return it in the response.

For this to work, we could create a new Lambda function to handle incoming requests for /hello/{name} - It'd look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import json


def hello_name(name):
    return {"statusCode": 200, "body": json.dumps({"message": f"hello {name}!"})}


def lambda_handler(event, context):
    name = event["pathParameters"]["name"]
    return hello_name(name)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: Sample SAM Template for powertools-quickstart
Globals:
    Function:
        Timeout: 3
Resources:
    HelloWorldFunction:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: hello_world/
            Handler: app.lambda_handler
            Runtime: python3.13
            Events:
                HelloWorld:
                    Type: Api
                    Properties:
                        Path: /hello
                        Method: get

    HelloWorldByNameFunctionName:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: hello_world/
            Handler: hello_by_name.lambda_handler
            Runtime: python3.13
            Events:
                HelloWorldName:
                    Type: Api
                    Properties:
                        Path: /hello/{name}
                        Method: get
Outputs:
    HelloWorldApi:
        Description: "API Gateway endpoint URL for Prod stage for Hello World function"
        Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/"
Question

But what happens if your application gets bigger and we need to cover numerous URL paths and HTTP methods for them?

This would quickly become non-trivial to maintain. Adding new Lambda function for each path, or multiple if/else to handle several routes & HTTP Methods can be error prone.

Creating our own router

Question

What if we create a simple router to reduce boilerplate?

We could group similar routes and intents, separate read and write operations resulting in fewer functions. It doesn't address the boilerplate routing code, but maybe it will be easier to add additional URLs.

Info: You might be already asking yourself about mono vs micro-functions

If you want a more detailed explanation of these two approaches, head over to the trade-offs on each approach later.

A first attempt at the routing logic might look similar to the following code snippet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
import json


def hello_name(event, **kargs):
    username = event["pathParameters"]["name"]
    return {"statusCode": 200, "body": json.dumps({"message": f"hello {username}!"})}


def hello(**kargs):
    return {"statusCode": 200, "body": json.dumps({"message": "hello unknown!"})}


class Router:
    def __init__(self):
        self.routes = {}

    def set(self, path, method, handler):
        self.routes[f"{path}-{method}"] = handler

    def get(self, path, method):
        try:
            route = self.routes[f"{path}-{method}"]
        except KeyError:
            raise RuntimeError(f"Cannot route request to the correct method. path={path}, method={method}")
        return route

router = Router()
router.set(path="/hello", method="GET", handler=hello)
router.set(path="/hello/{name}", method="GET", handler=hello_name)


def lambda_handler(event, context):
    path = event["resource"]
    http_method = event["httpMethod"]
    method = router.get(path=path, method=http_method)
    return method(event=event)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: Sample SAM Template for powertools-quickstart
Globals:
    Function:
        Timeout: 3
Resources:
    HelloWorldFunction:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: hello_world/
            Handler: app.lambda_handler
            Runtime: python3.13
            Events:
                HelloWorld:
                    Type: Api
                    Properties:
                        Path: /hello
                        Method: get
                HelloWorldName:
                    Type: Api
                    Properties:
                        Path: /hello/{name}
                        Method: get
Outputs:
    HelloWorldApi:
        Description: "API Gateway endpoint URL for Prod stage for Hello World function"
        Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/"

Let's break this down:

  • L4,9: We defined two hello_name and hello functions to handle /hello/{name} and /hello routes.
  • L13: We added a Router class to map a path, a method, and the function to call.
  • L27-29: We create a Router instance and map both /hello and /hello/{name}.
  • L35: We use Router's get method to retrieve a reference to the processing method (hello or hello_name).
  • L36: Finally, we run this method and send the results back to API Gateway.

This approach simplifies the configuration of our infrastructure since we have added all API Gateway paths in the HelloWorldFunction event section.

However, it forces us to understand the internal structure of the API Gateway request events, responses, and it could lead to other errors such as CORS not being handled properly, error handling, etc.

Simplifying with Event Handler

We can massively simplify cross-cutting concerns while keeping it lightweight by using Event Handler.

Tip

This is available for both REST API (API Gateway, ALB) and GraphQL API (AppSync).

Let's include Powertools for AWS Lambda (Python) as a dependency in requirement.txt, and use Event Handler to refactor our previous example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from aws_lambda_powertools.event_handler import APIGatewayRestResolver

app = APIGatewayRestResolver()


@app.get("/hello/<name>")
def hello_name(name):
    return {"message": f"hello {name}!"}


@app.get("/hello")
def hello():
    return {"message": "hello unknown!"}


def lambda_handler(event, context):
    return app.resolve(event, context)
1
aws-lambda-powertools[tracer]  # Tracer requires AWS X-Ray SDK dependency

Use sam build && sam local start-api and try run it locally again.

Note

If you're coming from Flask, you will be familiar with this experience already. Event Handler for API Gateway uses APIGatewayRestResolver to give a Flask-like experience while staying true to our tenet Keep it lean.

We have added the route annotation as the decorator for our methods. It enables us to use the parameters passed in the request directly, and our responses are simply dictionaries.

Lastly, we used return app.resolve(event, context) so Event Handler can resolve routes, inject the current request, handle serialization, route validation, etc.

From here, we could handle 404 routes, error handling, access query strings, payload, etc.

Tip

If you'd like to learn how python decorators work under the hood, you can follow Real Python's article.

Structured Logging

Over time, you realize that searching logs as text results in poor observability, it's hard to create metrics from, enumerate common exceptions, etc.

Then, you decided to propose production quality logging capabilities to your Lambda code. You found out that by having logs as JSON you can structure them, so that you can use any Log Analytics tool out there to quickly analyze them.

This helps not only in searching, but produces consistent logs containing enough context and data to ask arbitrary questions on the status of your system. We can take advantage of CloudWatch Logs and Cloudwatch Insight for this purpose.

JSON as output

The first option could be to use the standard Python Logger, and use a specialized library like pythonjsonlogger to create a JSON Formatter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import logging
import os

from pythonjsonlogger import jsonlogger
from aws_lambda_powertools.event_handler import APIGatewayRestResolver

logger = logging.getLogger("APP")
logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(fmt="%(asctime)s %(levelname)s %(name)s %(message)s")
logHandler.setFormatter(formatter)
logger.addHandler(logHandler)
logger.setLevel(os.getenv("POWERTOOLS_LOG_LEVEL", "INFO"))

app = APIGatewayRestResolver()


@app.get("/hello/<name>")
def hello_name(name):
    logger.info(f"Request from {name} received")
    return {"message": f"hello {name}!"}


@app.get("/hello")
def hello():
    logger.info("Request from unknown received")
    return {"message": "hello unknown!"}


def lambda_handler(event, context):
    logger.debug(event)
    return app.resolve(event, context)
1
2
aws-lambda-powertools
python-json-logger

With just a few lines our logs will now output to JSON format. We've taken the following steps to make that work:

  • L7: Creates an application logger named APP.
  • L8-11: Configures handler and formatter.
  • L12: Sets the logging level set in the POWERTOOLS_LOG_LEVEL environment variable, or INFO as a sentinel value.

After that, we use this logger in our application code to record the required information. We see logs structured as follows:

1
2
3
4
5
6
{
    "asctime": "2021-11-22 15:32:02,145",
    "levelname": "INFO",
    "name": "APP",
    "message"