feat: address Pablo's feedback with a decorator param

Author: heitorlessa

aws_lambda_powertools/metrics/metrics.py

@@ -128,6 +128,7 @@ def log_metrics(
         lambda_handler: Callable[[Any, Any], Any] = None,
         capture_cold_start_metric: bool = False,
         raise_on_empty_metrics: bool = False,
+        default_dimensions: Dict[str, str] = None,
     ):
         """Decorator to serialize and publish metrics at the end of a function execution.
 
@@ -150,11 +151,13 @@ def handler(event, context):
         Parameters
         ----------
         lambda_handler : Callable[[Any, Any], Any], optional
-            Lambda function handler, by default None
+            lambda function handler, by default None
         capture_cold_start_metric : bool, optional
-            Captures cold start metric, by default False
+            captures cold start metric, by default False
         raise_on_empty_metrics : bool, optional
-            Raise exception if no metrics are emitted, by default False
+            raise exception if no metrics are emitted, by default False
+        default_dimensions: Dict[str, str], optional
+            metric dimensions as key=value that will always be present
 
         Raises
         ------
@@ -170,11 +173,14 @@ def handler(event, context):
                 self.log_metrics,
                 capture_cold_start_metric=capture_cold_start_metric,
                 raise_on_empty_metrics=raise_on_empty_metrics,
+                default_dimensions=default_dimensions,
             )
 
         @functools.wraps(lambda_handler)
         def decorate(event, context):
             try:
+                if default_dimensions:
+                    self.set_default_dimensions(**default_dimensions)
                 response = lambda_handler(event, context)
                 if capture_cold_start_metric:
                     self.__add_cold_start_metric(context=context)

docs/core/metrics.md

@@ -107,11 +107,11 @@ You can create metrics using `add_metric`, and you can create dimensions for all
 
 ### Adding default dimensions
 
-You can add default metric dimensions to ensure they are persisted across Lambda invocations using `set_default_dimenions`.
+You can use either `set_default_dimensions` method or `default_permissions` parameter in `log_metrics` decorator to persist dimensions across Lambda invocations.
 
 If you'd like to remove them at some point, you can use `clear_default_dimensions` method.
 
-=== "Default dimensions"
+=== "set_default_dimensions method"
 
     ```python hl_lines="5"
 	from aws_lambda_powertools import Metrics
@@ -124,6 +124,19 @@ If you'd like to remove them at some point, you can use `clear_default_dimension
 	def lambda_handler(evt, ctx):
 		metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)
 	```
+=== "with log_metrics decorator"
+
+    ```python hl_lines="5 7"
+	from aws_lambda_powertools import Metrics
+	from aws_lambda_powertools.metrics import MetricUnit
+
+	metrics = Metrics(namespace="ExampleApplication", service="booking")
+	DEFAULT_DIMENSIONS = {"environment": "prod", "another": "one"}
+
+	@metrics.log_metrics(default_dimensions=DEFAULT_DIMENSIONS)
+	def lambda_handler(evt, ctx):
+		metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)
+	```
 
 ### Flushing metrics
 

tests/functional/test_metrics.py

@@ -798,3 +798,27 @@ def test_default_dimensions_across_instances(namespace):
 
     # THEN default dimensions should also be present
     assert "environment" in same_metrics.default_dimensions
+
+
+def test_log_metrics_with_default_dimensions(capsys, metrics, dimensions, namespace):
+    # GIVEN Metrics is initialized
+    my_metrics = Metrics(namespace=namespace)
+    default_dimensions = {"environment": "test", "log_group": "/lambda/test"}
+
+    # WHEN we utilize log_metrics with default dimensions to serialize
+    # and flush metrics and clear all metrics and dimensions from memory
+    # at the end of a function execution
+    @my_metrics.log_metrics(default_dimensions=default_dimensions)
+    def lambda_handler(evt, ctx):
+        for metric in metrics:
+            my_metrics.add_metric(**metric)
+
+    lambda_handler({}, {})
+    first_invocation = capture_metrics_output(capsys)
+
+    lambda_handler({}, {})
+    second_invocation = capture_metrics_output(capsys)
+
+    # THEN we should have default dimensions in both outputs
+    assert "environment" in first_invocation
+    assert "environment" in second_invocation