v1.0.0
release-drafter
released this
18 Jun 15:48
·
3474 commits
to develop
since this release
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
- Enable via
- 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%
- Enable via
- 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
- You can now import core utilities more easily
- 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 constructorMetrics(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