docs(metrics): snippets split, improved, and lint (aws-powertools#1272)

Author: heitorlessa

docs/core/metrics.md

@@ -76,7 +76,7 @@ You can trace asynchronous functions and generator functions (including context
 
 === "Async"
 
-    ```python hl_lines="8"
+    ```python hl_lines="9"
     --8<-- "examples/tracer/src/capture_method_async.py"
     ```
 

docs/core/tracer.md

@@ -0,0 +1,25 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: AWS Lambda Powertools Metrics doc examples
+
+Globals:
+  Function:
+    Timeout: 5
+    Runtime: python3.9
+    Tracing: Active
+    Environment:
+      Variables:
+        POWERTOOLS_SERVICE_NAME: booking
+        POWERTOOLS_METRICS_NAMESPACE: ServerlessAirline
+
+    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:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: ../src
+      Handler: capture_lambda_handler.handler

examples/metrics/sam/template.yaml

@@ -0,0 +1,14 @@
+import os
+
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+STAGE = os.getenv("STAGE", "dev")
+metrics = Metrics()
+
+
+@metrics.log_metrics  # ensures metrics are flushed upon request completion/failure
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_dimension(name="environment", value=STAGE)
+    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

examples/metrics/src/add_dimension.py

@@ -0,0 +1,13 @@
+from uuid import uuid4
+
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+metrics = Metrics()
+
+
+@metrics.log_metrics
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)
+    metrics.add_metadata(key="booking_id", value=f"{uuid4()}")

examples/metrics/src/add_metadata.py

@@ -0,0 +1,26 @@
+{
+    "_aws": {
+        "Timestamp": 1656688250155,
+        "CloudWatchMetrics": [
+            {
+                "Namespace": "ServerlessAirline",
+                "Dimensions": [
+                    [
+                        "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                        "Name": "SuccessfulBooking",
+                        "Unit": "Count"
+                    }
+                ]
+            }
+        ]
+    },
+    "service": "booking",
+    "booking_id": "00347014-341d-4b8e-8421-a89d3d588ab3",
+    "SuccessfulBooking": [
+        1.0
+    ]
+}

examples/metrics/src/add_metadata_output.json

@@ -0,0 +1,10 @@
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+metrics = Metrics()
+
+
+@metrics.log_metrics  # ensures metrics are flushed upon request completion/failure
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

examples/metrics/src/add_metrics.py

@@ -0,0 +1,15 @@
+import os
+
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+STAGE = os.getenv("STAGE", "dev")
+metrics = Metrics()
+
+
+@metrics.log_metrics  # ensures metrics are flushed upon request completion/failure
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_dimension(name="environment", value=STAGE)
+    metrics.add_metric(name="TurbineReads", unit=MetricUnit.Count, value=1)
+    metrics.add_metric(name="TurbineReads", unit=MetricUnit.Count, value=8)

examples/metrics/src/add_multi_value_metrics.py

@@ -0,0 +1,28 @@
+{
+    "_aws": {
+        "Timestamp": 1656685750622,
+        "CloudWatchMetrics": [
+            {
+                "Namespace": "ServerlessAirline",
+                "Dimensions": [
+                    [
+                        "environment",
+                        "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                        "Name": "TurbineReads",
+                        "Unit": "Count"
+                    }
+                ]
+            }
+        ]
+    },
+    "environment": "dev",
+    "service": "booking",
+    "TurbineReads": [
+        1.0,
+        8.0
+    ]
+}

examples/metrics/src/add_multi_value_metrics_output.json

@@ -0,0 +1,34 @@
+import json
+from dataclasses import dataclass
+
+import assert_multiple_emf_blobs_module
+import pytest
+
+
+@pytest.fixture
+def lambda_context():
+    @dataclass
+    class LambdaContext:
+        function_name: str = "test"
+        memory_limit_in_mb: int = 128
+        invoked_function_arn: str = "arn:aws:lambda:eu-west-1:809313241:function:test"
+        aws_request_id: str = "52fdfc07-2182-154f-163f-5f0f9a621d72"
+
+    return LambdaContext()
+
+
+def capture_metrics_output_multiple_emf_objects(capsys):
+    return [json.loads(line.strip()) for line in capsys.readouterr().out.split("\n") if line]
+
+
+def test_log_metrics(capsys, lambda_context):
+    assert_multiple_emf_blobs_module.lambda_handler({}, lambda_context)
+
+    cold_start_blob, custom_metrics_blob = capture_metrics_output_multiple_emf_objects(capsys)
+
+    # Since `capture_cold_start_metric` is used
+    # we should have one JSON blob for cold start metric and one for the application
+    assert cold_start_blob["ColdStart"] == [1.0]
+    assert cold_start_blob["function_name"] == "test"
+
+    assert "SuccessfulBooking" in custom_metrics_blob