Tutorial
This tutorial progressively introduces Powertools for AWS Lambda (Python) core utilities by using one feature at a time.
Requirements¶
- AWS CLI and configured with your credentials.
- AWS SAM CLI installed.
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 | |
| Use SAM CLI to initialize the sample project | |
|---|---|
1 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
Let's break this down:
- L4,9: We defined two
hello_nameandhellofunctions to handle/hello/{name}and/helloroutes. - L13: We added a
Routerclass to map a path, a method, and the function to call. - L27-29: We create a
Routerinstance and map both/helloand/hello/{name}. - L35: We use Router's
getmethod to retrieve a reference to the processing method (helloorhello_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 | |
1 | |
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 | |
1 2 | |
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_LEVELenvironment variable, orINFOas 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 | |