aws-lambda-powertools 1.0.0

v1.0.0

on Python PyPI

Changes

With this release, we move from release candidate to General Availability 🎉🎉🎉!

This means APIs for the core utilities Tracer, Logger, and Metrics as well as Middleware factory are now stable.

Quick links: 📜Documentation | 🐍PyPi | Feature request | Bug Report | Kitchen sink example

Tracer

🤩 Key features 🤩

• Capture cold start as annotation, and responses as well as full exceptions as metadata
• Run functions locally with SAM CLI without code change to disable tracing
• Explicitly disable tracing via env var POWERTOOLS_TRACE_DISABLED="true"
• Support tracing async methods
• Auto patch supported modules, or a tuple of explicit modules supported by AWS X-Ray

from aws_lambda_powertools import Tracer


tracer = Tracer()

@tracer.capture_method
def collect_payment(charge_id: str):
    ...

@tracer.capture_lambda_handler
def handler(event, context):
    charge_id = event.get('charge_id')
    payment = collect_payment(charge_id)
    ...

Logger

🤩 Key features 🤩

• Capture key fields from Lambda context, cold start and structures logging output as JSON
• Log Lambda event when instructed (disabled by default)
  • Enable via POWERTOOLS_LOGGER_LOG_EVENT="true" or explicitly via decorator param
• Log sampling enables DEBUG log level for a percentage of requests (disabled by default)
  • Enable via POWERTOOLS_LOGGER_SAMPLE_RATE=0.1, ranges from 0 to 1, where 0.1 is 10% and 1 is 100%
• Append additional keys to structured log at any point in time

from aws_lambda_powertools import Logger


logger = Logger(sample_rate=0.1) # sample 1% of debugging logs

@logger.inject_lambda_context # add contextual lambda runtime info to structured logging
def handler(event, context):
    logger.info("Collecting payment")

    # You can log entire objects too
    logger.info({
        "operation": "collect_payment",
        "charge_id": event['charge_id']
    })

    # Exceptions will be structured under `exceptions` key
    logger.exception(ValueError("Incorrect user id"))

Metrics

🤩 Key features 🤩

• Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
• Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)
• Metrics are created asynchronously by CloudWatch service, no custom stacks needed
• Context manager to create an one off metric with a different dimension

from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit


@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event, context):
    ...
    check_out_cart()  # Function to process the checkout
    metrics.add_metric(name="CartCheckedOut", unit=MetricUnit.Count, value=1)

Bring your own middleware

🤩 Key features 🤩

• Run logic before, after, and handle exceptions
• Trace each middleware when requested

from aws_lambda_powertools.middleware_factory import lambda_handler_decorator


@lambda_handler_decorator(trace_execution=True)
def my_middleware(handler, event, context):
    return handler(event, context)

@my_middleware
def lambda_handler(event, context):
    ...

Sample projects using Powertools

• Serverless shopping cart microservice
• Serverless e-commerce platform
• Serverless Airline
  • Airline project is still using the original version as a shared lib; we'll migrate to this version afterwards

🌟Special thank you

We'd like to extend our gratitude to the following people who helped with contributions, feedbacks, and their opinions while we were in Beta:

@cakepietoast, @nmoutschen, @jfuss, @danilohgds, @pcolazurdo, @marcioemiranda, @bahrmichael, @keithrozario, @ranman

🧐What's New for Beta customers

If you've been following the Beta, these are the new changes available in GA:

• Metrics:
  • add_metadata method to add any metric metadata you'd like to ease finding metric related data via CloudWatch Logs
  • new parameter to log_metrics decorator to create a cold start metric to remove unnecessary boilerplate capture_cold_start_metric=True
• Logger:
  • new method structure_logs(append=True, **kwargs) you can use to append additional keys you want available across all log statements
• High level imports
  • You can now import core utilities more easily from aws_lambda_powertools import Tracer, Metrics, Logger
• Contributors:
  • new Contributing guide with instructions on how to setup dev env, and running documentation locally - both docs website as well as API reference website

Breaking and subtle changes from beta to GA:

• Metrics:
  • add_namespace has been removed in favour of a new parameter in the constructor Metrics(namespace="ServerlessBooking")
  • Empty metrics no longer return SchemaValidationError and are an opt-in behaviour
• Logger
  • log_metrics has been removed in favour of Metrics
• Tracer
  • capture_method supports both sync and async functions
  • Escape hatch mechanism to use methods/functions from AWS X-Ray SDK