docs(metrics): snippets split, improved, and lint

docs/core/tracer.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"
     ```
 

examples/metrics/sam/template.yaml

@@ -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/src/add_dimension.py

@@ -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_metadata.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_output.json

@@ -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_metrics.py

@@ -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_multi_value_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_output.json

@@ -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/assert_multiple_emf_blobs.py

@@ -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

examples/metrics/src/assert_multiple_emf_blobs_module.py

@@ -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(capture_cold_start_metric=True)
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

examples/metrics/src/assert_single_emf_blob.py

@@ -0,0 +1,15 @@
+import json
+
+import add_metrics
+
+
+def test_log_metrics(capsys):
+    add_metrics.lambda_handler({}, {})
+
+    log = capsys.readouterr().out.strip()  # remove any extra line
+    metrics_output = json.loads(log)  # deserialize JSON str
+
+    # THEN we should have no exceptions
+    # and a valid EMF object should be flushed correctly
+    assert "SuccessfulBooking" in log  # basic string assertion in JSON str
+    assert "SuccessfulBooking" in metrics_output["_aws"]["CloudWatchMetrics"][0]["Metrics"][0]["Name"]

examples/metrics/src/capture_cold_start_metric.py

@@ -0,0 +1,9 @@
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+metrics = Metrics()
+
+
+@metrics.log_metrics(capture_cold_start_metric=True)
+def lambda_handler(event: dict, context: LambdaContext):
+    ...

examples/metrics/src/capture_cold_start_metric_output.json

@@ -0,0 +1,27 @@
+{
+    "_aws": {
+        "Timestamp": 1656687493142,
+        "CloudWatchMetrics": [
+            {
+                "Namespace": "ServerlessAirline",
+                "Dimensions": [
+                    [
+                        "function_name",
+                        "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                        "Name": "ColdStart",
+                        "Unit": "Count"
+                    }
+                ]
+            }
+        ]
+    },
+    "function_name": "test",
+    "service": "booking",
+    "ColdStart": [
+        1.0
+    ]
+}

examples/metrics/src/clear_metrics_in_tests.py

@@ -0,0 +1,14 @@
+import pytest
+
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import metrics as metrics_global
+
+
+@pytest.fixture(scope="function", autouse=True)
+def reset_metric_set():
+    # Clear out every metric data prior to every test
+    metrics = Metrics()
+    metrics.clear_metrics()
+    metrics_global.is_cold_start = True  # ensure each test has cold start
+    metrics.clear_default_dimensions()  # remove persisted default dimensions, if any
+    yield

examples/metrics/src/log_metrics_output.json

@@ -0,0 +1,25 @@
+{
+    "_aws": {
+        "Timestamp": 1656686788803,
+        "CloudWatchMetrics": [
+            {
+                "Namespace": "ServerlessAirline",
+                "Dimensions": [
+                    [
+                        "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                        "Name": "SuccessfulBooking",
+                        "Unit": "Count"
+                    }
+                ]
+            }
+        ]
+    },
+    "service": "booking",
+    "SuccessfulBooking": [
+        1.0
+    ]
+}

examples/metrics/src/manual_flush.py

@@ -0,0 +1,14 @@
+import json
+
+from aws_lambda_powertools import Metrics
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+metrics = Metrics()
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)
+    your_metrics_object = metrics.serialize_metric_set()
+    metrics.clear_metrics()
+    print(json.dumps(your_metrics_object))

examples/metrics/src/raise_on_empty_metrics.py

@@ -0,0 +1,10 @@
+from aws_lambda_powertools.metrics import Metrics
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+metrics = Metrics()
+
+
+@metrics.log_metrics(raise_on_empty_metrics=True)
+def lambda_handler(event: dict, context: LambdaContext):
+    # no metrics being created will now raise SchemaValidationError
+    ...

examples/metrics/src/run_tests_env_var.sh

@@ -0,0 +1 @@
+POWERTOOLS_SERVICE_NAME="booking" POWERTOOLS_METRICS_NAMESPACE="ServerlessAirline" python -m pytest

examples/metrics/src/set_default_dimensions.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.set_default_dimensions(environment=STAGE, another="one")
+
+
+@metrics.log_metrics  # ensures metrics are flushed upon request completion/failure
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_metric(name="TurbineReads", unit=MetricUnit.Count, value=1)
+    metrics.add_metric(name="TurbineReads", unit=MetricUnit.Count, value=8)

examples/metrics/src/set_default_dimensions_log_metrics.py

@@ -0,0 +1,16 @@
+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()
+DEFAULT_DIMENSIONS = {"environment": STAGE, "another": "one"}
+
+
+# ensures metrics are flushed upon request completion/failure
+@metrics.log_metrics(default_dimensions=DEFAULT_DIMENSIONS)
+def lambda_handler(event: dict, context: LambdaContext):
+    metrics.add_metric(name="TurbineReads", unit=MetricUnit.Count, value=1)
+    metrics.add_metric(name="TurbineReads", unit=MetricUnit.Count, value=8)

examples/metrics/src/single_metric.py

@@ -0,0 +1,12 @@
+import os
+
+from aws_lambda_powertools import single_metric
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+STAGE = os.getenv("STAGE", "dev")
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    with single_metric(name="MySingleMetric", unit=MetricUnit.Count, value=1) as metric:
+        metric.add_dimension(name="environment", value=STAGE)

examples/metrics/src/single_metric_output.json

@@ -0,0 +1,27 @@
+{
+    "_aws": {
+        "Timestamp": 1656689267834,
+        "CloudWatchMetrics": [
+            {
+                "Namespace": "ServerlessAirline",
+                "Dimensions": [
+                    [
+                        "environment",
+                        "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                        "Name": "MySingleMetric",
+                        "Unit": "Count"
+                    }
+                ]
+            }
+        ]
+    },
+    "environment": "dev",
+    "service": "booking",
+    "MySingleMetric": [
+        1.0
+    ]
+}

examples/tracer/sam/template.yaml

@@ -9,7 +9,7 @@ Globals:
     Tracing: Active
     Environment:
       Variables:
-        POWERTOOLS_SERVICE_NAME: example
+        POWERTOOLS_SERVICE_NAME: payment
     Layers:
       # Find the latest Layer version in the official documentation
       # https://awslabs.github.io/aws-lambda-powertools-python/latest/#lambda-layer