Merge branch 'develop' of https://github.com/awslabs/aws-lambda-powertools-python into develop

* 'develop' of https://github.com/awslabs/aws-lambda-powertools-python:
  docs(logger): snippets split, improved, and lint (#1262)

Author: heitorlessa

docs/core/logger.md

@@ -21,7 +21,7 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray Python SDK](https://github.
 Before your use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray.
 
 ```yaml hl_lines="9 12" title="AWS Serverless Application Model (SAM) example"
---8<-- "examples/tracer/template.yaml"
+--8<-- "examples/tracer/sam/template.yaml"
 ```
 
 ### Lambda handler

docs/core/tracer.md

@@ -9,15 +9,16 @@ Globals:
     Tracing: Active
     Environment:
       Variables:
-        POWERTOOLS_SERVICE_NAME: example
+        POWERTOOLS_SERVICE_NAME: payment
+        LOG_LEVEL: INFO
     Layers:
       # Find the latest Layer version in the official documentation
       # https://awslabs.github.io/aws-lambda-powertools-python/latest/#lambda-layer
       - !Sub arn:aws:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPython:21
 
 Resources:
-  CaptureLambdaHandlerExample:
+  LoggerLambdaHandlerExample:
     Type: AWS::Serverless::Function
     Properties:
-      CodeUri: src
-      Handler: capture_lambda_handler.handler
+      CodeUri: ../src
+      Handler: inject_lambda_context.handler

examples/tracer/template.yaml renamed to examples/logger/sam/template.yaml

@@ -0,0 +1,15 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+def handler(event: dict, context: LambdaContext) -> str:
+    order_id = event.get("order_id")
+
+    # this will ensure order_id key always has the latest value before logging
+    # alternative, you can use `clear_state=True` parameter in @inject_lambda_context
+    logger.append_keys(order_id=order_id)
+    logger.info("Collecting payment")
+
+    return "hello world"

examples/logger/src/append_keys.py

@@ -0,0 +1,11 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+def handler(event: dict, context: LambdaContext) -> str:
+    fields = {"request_id": "1123"}
+    logger.info("Collecting payment", extra=fields)
+
+    return "hello world"

examples/logger/src/append_keys_extra.py

@@ -0,0 +1,8 @@
+{
+    "level": "INFO",
+    "location": "collect.handler:9",
+    "message": "Collecting payment",
+    "timestamp": "2021-05-03 11:47:12,494+0200",
+    "service": "payment",
+    "request_id": "1123"
+}

examples/logger/src/append_keys_extra_output.json

@@ -0,0 +1,8 @@
+{
+    "level": "INFO",
+    "location": "collect.handler:11",
+    "message": "Collecting payment",
+    "timestamp": "2021-05-03 11:47:12,494+0200",
+    "service": "payment",
+    "order_id": "order_id_value"
+}

examples/logger/src/append_keys_output.json

@@ -0,0 +1,28 @@
+import os
+
+import requests
+
+from aws_lambda_powertools import Logger
+
+ENDPOINT = os.getenv("PAYMENT_API", "")
+logger = Logger(service="payment")
+
+
+class PaymentError(Exception):
+    ...
+
+
+def handler(event, context):
+    logger.append_keys(payment_id="123456789")
+    charge_id = event.get("charge_id", "")
+
+    try:
+        ret = requests.post(url=f"{ENDPOINT}/collect", data={"charge_id": charge_id})
+        ret.raise_for_status()
+
+        logger.info("Charge collected successfully", extra={"charge_id": charge_id})
+        return ret.json()
+    except requests.HTTPError as e:
+        raise PaymentError(f"Unable to collect payment for charge {charge_id}") from e
+
+    logger.info("goodbye")

examples/logger/src/append_keys_vs_extra.py

@@ -0,0 +1,21 @@
+[
+    {
+        "level": "INFO",
+        "location": "<module>:22",
+        "message": "Charge collected successfully",
+        "timestamp": "2021-01-12 14:09:10,859",
+        "service": "payment",
+        "sampling_rate": 0.0,
+        "payment_id": "123456789",
+        "charge_id": "75edbad0-0857-4fc9-b547-6180e2f7959b"
+    },
+    {
+        "level": "INFO",
+        "location": "<module>:27",
+        "message": "goodbye",
+        "timestamp": "2021-01-12 14:09:10,860",
+        "service": "payment",
+        "sampling_rate": 0.0,
+        "payment_id": "123456789"
+    }
+]

examples/logger/src/append_keys_vs_extra_output.json

@@ -0,0 +1,13 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.logging.formatter import LambdaPowertoolsFormatter
+
+
+class CustomFormatter(LambdaPowertoolsFormatter):
+    def serialize(self, log: dict) -> str:
+        """Serialize final structured log dict to JSON str"""
+        log["event"] = log.pop("message")  # rename message key to event
+        return self.json_serializer(log)  # use configured json serializer
+
+
+logger = Logger(service="payment", logger_formatter=CustomFormatter())
+logger.info("hello")