A suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier - Currently available for Python only and compatible with Python >=3.6.

Status: Beta

Tracing

It currently uses AWS X-Ray

• Decorators that capture cold start as annotation, and response and exceptions as metadata
• Run functions locally without code change to disable tracing
• Explicitly disable tracing via env var POWERTOOLS_TRACE_DISABLED="true"

Logging

• Decorators that capture key fields from Lambda context, cold start and structures logging output as JSON
• Optionally log Lambda request when instructed (disabled by default)
  • Enable via POWERTOOLS_LOGGER_LOG_EVENT="true" or explicitly via decorator param
• Logs canonical custom metric line to logs that can be consumed asynchronously

Environment variables used across suite of utilities

With pip installed, run: pip install aws-lambda-powertools

Example SAM template using supported environment variables

Globals: Function: Tracing: Active # can also be enabled per function Environment: Variables: POWERTOOLS_SERVICE_NAME: "payment" POWERTOOLS_TRACE_DISABLED: "false" 

Pseudo Python Lambda code

from aws_lambda_powertools.tracing import Tracer tracer = Tracer() # tracer = Tracer(service="payment") # can also be explicitly defined @tracer.capture_method def collect_payment(charge_id): # logic ret = requests.post(PAYMENT_ENDPOINT) # custom annotation tracer.put_annotation("PAYMENT_STATUS", "SUCCESS") return ret @tracer.capture_lambda_handler def handler(event, context) charge_id = event.get('charge_id') payment = collect_payment(charge_id) ...

Example SAM template using supported environment variables

Globals: Function: Environment: Variables: POWERTOOLS_SERVICE_NAME: "payment" LOG_LEVEL: "INFO"

Pseudo Python Lambda code

from aws_lambda_powertools.logging import logger_setup, logger_inject_lambda_context logger = logger_setup() # logger_setup(service="payment") # also accept explicit service name # logger_setup(level="INFO") # also accept explicit log level @logger_inject_lambda_context def handler(event, context) logger.info("Collecting payment") ... # You can log entire objects too logger.info({ "operation": "collect_payment", "charge_id": event['charge_id'] }) ...

Exerpt output in CloudWatch Logs

{ "timestamp":"2019-08-22 18:17:33,774", "level":"INFO", "location":"collect.handler:1", "service":"payment", "lambda_function_name":"test", "lambda_function_memory_size":"128", "lambda_function_arn":"arn:aws:lambda:eu-west-1:12345678910:function:test", "lambda_request_id":"52fdfc07-2182-154f-163f-5f0f9a621d72", "cold_start": "true", "message": "Collecting payment" } { "timestamp":"2019-08-22 18:17:33,774", "level":"INFO", "location":"collect.handler:15", "service":"payment", "lambda_function_name":"test", "lambda_function_memory_size":"128", "lambda_function_arn":"arn:aws:lambda:eu-west-1:12345678910:function:test", "lambda_request_id":"52fdfc07-2182-154f-163f-5f0f9a621d72", "cold_start": "true", "message":{ "operation":"collect_payment", "charge_id": "ch_AZFlk2345C0" } }

This feature requires Custom Metrics SAR App in order to process canonical metric lines in CloudWatch Logs.

If you're starting from scratch, you may want to see a working example, tune to your needs and deploy within your account - Serverless Airline Log Processing Stack

from aws_lambda_powertools.logging import MetricUnit, log_metric def handler(event, context) log_metric(name="SuccessfulPayment", unit=MetricUnit.Count, value=10, namespace="MyApplication") # Optional dimensions log_metric(name="SuccessfulPayment", unit=MetricUnit.Count, value=10, namespace="MyApplication", customer_id="123-abc", charge_id="abc-123") # Explicit service name log_metric(service="paymentTest", name="SuccessfulPayment", namespace="MyApplication".....) ...

Exerpt output in CloudWatch Logs

MONITORING|10|Count|SuccessfulPayment|MyApplication|service="payment MONITORING|10|Count|SuccessfulPayment|MyApplication|customer_id="123-abc",charge_id="abc-123",service="payment MONITORING|10|Count|SuccessfulPayment|MyApplication|service="paymentTest 

This library may change its API/methods or environment variables as it receives feedback from customers. Currently looking for ideas in the following areas before making it stable:

• Should Tracer patch all possible imported libraries by default or only AWS SDKs?
  • Patching all libraries may have a small performance penalty (~50ms) at cold start
  • Alternatively, we could patch only AWS SDK if available and to provide a param to patch multiple Tracer(modules=("boto3", "requests"))
• Create a Tracer provider to support additional tracing
  • Either duck typing or ABC to allow additional tracing providers

• Enable CI
• Add an example code using powertools
• Automate release and version bumping in CI

• Structured logging initial implementation from aws-lambda-logging
• Powertools idea DAZN Powertools

This library is licensed under the MIT-0 License. See the LICENSE file.