/

Homepage

AWS Lambda Powertools Python


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

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

hello_world.sh
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).

AppARN
aws-lambda-powertools-python-layerarn: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

UtilityDescription
TracingDecorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
LoggingStructured logging made easier, and decorator to enrich structured logging with key Lambda context details
MetricsCustom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
Bring your own middlewareDecorator factory to create your own middleware to run logic before, and after each Lambda invocation
ParametersRetrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time
TypingStatic typing classes to speedup development in your IDE
BatchHandle partial failures for AWS SQS batch processing
ValidationJSON Schema validator for inbound events and responses
Event source data classesData classes describing the schema of common Lambda event triggers

Environment variables

Environment variables used across suite of utilities.

Environment variableDescriptionUtility
POWERTOOLS_SERVICE_NAMESets service name used for tracing namespace, metrics dimension and structured loggingAll
POWERTOOLS_METRICS_NAMESPACESets namespace used for metricsMetrics
POWERTOOLS_TRACE_DISABLEDDisables tracingTracing
POWERTOOLS_TRACE_MIDDLEWARESCreates sub-segment for each custom middlewareMiddleware factory
POWERTOOLS_LOGGER_LOG_EVENTLogs incoming eventLogging
POWERTOOLS_LOGGER_SAMPLE_RATEDebug log samplingLogging
LOG_LEVELSets logging levelLogging

Debug mode

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

app.py
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.

Edit on GitHub