Skip to content

Latest commit

 

History

History
150 lines (116 loc) · 7.86 KB

index.mdx

File metadata and controls

150 lines (116 loc) · 7.86 KB
title description
Homepage
AWS Lambda Powertools Python

import Note from "../src/components/Note"

A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more.

Looking for a quick run through of the core utilities?

Check out this detailed blog post with a practical example.

Install

Powertools is available in PyPi. You can use your favourite dependency management tool to install it

  • poetry: poetry add aws-lambda-powertools
  • pip: pip install aws-lambda-powertools

Quick hello world example using SAM CLI

sam init --location https://github.com/aws-samples/cookiecutter-aws-sam-python

Lambda Layer

Powertools is also available as a Lambda Layer. It is distributed via the AWS Serverless Application Repository (SAR).

App ARN
aws-lambda-powertools-python-layer arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer

If using SAM, you can include this SAR App as part of your shared Layers stack, and lock to a specific semantic version. Once deployed, it'll be available across the account this is deployed to.

  AwsLambdaPowertoolsPythonLayer:
    Type: AWS::Serverless::Application
    Properties:
      Location:
        ApplicationId: arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer
        SemanticVersion: 1.3.1 # change to latest semantic version available in SAR

This will add a nested app stack with an output parameter LayerVersionArn, that you can reference inside your Lambda function definition:

  Layers:
    - !GetAtt AwsLambdaPowertoolsPythonLayer.Outputs.LayerVersionArn

Here is the list of IAM permissions that you need to add to your deployment IAM role to use the layer:

Version: '2012-10-17'
Statement:
  - Sid: CloudFormationTransform
    Effect: Allow
    Action: cloudformation:CreateChangeSet
    Resource:
      - arn:aws:cloudformation:us-east-1:aws:transform/Serverless-2016-10-31
  - Sid: GetCfnTemplate
    Effect: Allow
    Action:
      - serverlessrepo:CreateCloudFormationTemplate
      - serverlessrepo:GetCloudFormationTemplate
    Resource:
      # this is arn of the powertools SAR app
      - arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer
  - Sid: S3AccessLayer
    Effect: Allow
    Action:
      - s3:GetObject
    Resource:
      # AWS publishes to an external S3 bucket locked down to your account ID
      # The below example is us publishing lambda powertools
      # Bucket: awsserverlessrepo-changesets-plntc6bfnfj
      # Key: *****/arn:aws:serverlessrepo:eu-west-1:057560766410:applications-aws-lambda-powertools-python-layer-versions-1.6.0/aeeccf50-****-****-****-*********
      - arn:aws:s3:::awsserverlessrepo-changesets-*/*
  - Sid: GetLayerVersion
    Effect: Allow
    Action:
      - lambda:PublishLayerVersion
      - lambda:GetLayerVersion
    Resource:
      - !Sub arn:aws:lambda:${AWS::Region}:${AWS::AccoundId}:layer:aws-lambda-powertools-python-layer*

Credits to mwarkentin for providing the scoped down IAM permissions.

The region and the account id for CloudFormationTransform and GetCfnTemplat are fixed.

You can fetch the available versions via the API with:

aws serverlessrepo list-application-versions \
  --application-id arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer

Features

Utility Description
Tracing Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
Logging Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
Metrics Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
Bring your own middleware Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
Parameters Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time
Typing Static typing classes to speedup development in your IDE
Batch Handle partial failures for AWS SQS batch processing
Validation JSON Schema validator for inbound events and responses
Event source data classes Data classes describing the schema of common Lambda event triggers

Environment variables

Environment variables used across suite of utilities.

Environment variable | Description | Utility ------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- POWERTOOLS_SERVICE_NAME | Sets service name used for tracing namespace, metrics dimension and structured logging | All POWERTOOLS_METRICS_NAMESPACE | Sets namespace used for metrics | Metrics POWERTOOLS_TRACE_DISABLED | Disables tracing | Tracing POWERTOOLS_TRACE_MIDDLEWARES | Creates sub-segment for each custom middleware | Middleware factory POWERTOOLS_LOGGER_LOG_EVENT | Logs incoming event | Logging POWERTOOLS_LOGGER_SAMPLE_RATE | Debug log sampling | Logging LOG_LEVEL | Sets logging level | Logging

Debug mode

As a best practice, AWS Lambda Powertools logging statements are suppressed. If necessary, you can enable debugging using set_package_logger:

from aws_lambda_powertools.logging.logger import set_package_logger

set_package_logger()

Tenets

  • AWS Lambda only – We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
  • Eases the adoption of best practices – The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
  • Keep it lean – Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
  • We strive for backwards compatibility – New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
  • We work backwards from the community – We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
  • Idiomatic – Utilities follow programming language idioms and language-specific best practices.

* Core utilities are Tracer, Logger and Metrics. Optional utilities may vary across languages.