feat: add metrics metadata #80

Author: heitorlessa

aws_lambda_powertools/metrics/base.py

@@ -5,7 +5,7 @@
 import os
 import pathlib
 from enum import Enum
-from typing import Dict, List, Union
+from typing import Any, Dict, List, Union
 
 import fastjsonschema
 
@@ -78,14 +78,20 @@ class MetricManager:
     """
 
     def __init__(
-        self, metric_set: Dict[str, str] = None, dimension_set: Dict = None, namespace: str = None, service: str = None
+        self,
+        metric_set: Dict[str, str] = None,
+        dimension_set: Dict = None,
+        namespace: str = None,
+        metadata_set: Dict[str, Any] = None,
+        service: str = None,
     ):
         self.metric_set = metric_set if metric_set is not None else {}
         self.dimension_set = dimension_set if dimension_set is not None else {}
         self.namespace = namespace or os.getenv("POWERTOOLS_METRICS_NAMESPACE")
         self.service = service or os.environ.get("POWERTOOLS_SERVICE_NAME")
         self._metric_units = [unit.value for unit in MetricUnit]
         self._metric_unit_options = list(MetricUnit.__members__)
+        self.metadata_set = self.metadata_set if metadata_set is not None else {}
 
     def add_metric(self, name: str, unit: MetricUnit, value: Union[float, int]):
         """Adds given metric
@@ -131,7 +137,7 @@ def add_metric(self, name: str, unit: MetricUnit, value: Union[float, int]):
             # since we could have more than 100 metrics
             self.metric_set.clear()
 
-    def serialize_metric_set(self, metrics: Dict = None, dimensions: Dict = None) -> Dict:
+    def serialize_metric_set(self, metrics: Dict = None, dimensions: Dict = None, metadata: Dict = None) -> Dict:
         """Serializes metric and dimensions set
 
         Parameters
@@ -165,6 +171,9 @@ def serialize_metric_set(self, metrics: Dict = None, dimensions: Dict = None) ->
         if dimensions is None:  # pragma: no cover
             dimensions = self.dimension_set
 
+        if metadata is None:  # pragma: no cover
+            metadata = self.metadata_set
+
         if self.service and not self.dimension_set.get("service"):
             self.dimension_set["service"] = self.service
 
@@ -190,6 +199,7 @@ def serialize_metric_set(self, metrics: Dict = None, dimensions: Dict = None) ->
         metrics_timestamp = {"Timestamp": int(datetime.datetime.now().timestamp() * 1000)}
         metric_set["_aws"] = {**metrics_timestamp, **metrics_definition}
         metric_set.update(**dimensions)
+        metric_set.update(**metadata)
 
         try:
             logger.debug("Validating serialized metrics against CloudWatch EMF schema", metric_set)
@@ -225,6 +235,38 @@ def add_dimension(self, name: str, value: str):
         else:
             self.dimension_set[name] = str(value)
 
+    def add_metadata(self, key: str, value: Any):
+        """Adds high cardinal metadata for metrics object
+
+        This will not be available during metrics visualization.
+        Instead, this will be searchable through logs.
+
+        If you're looking to add metadata to filter metrics, then
+        use add_dimensions method.
+
+        Example
+        -------
+        **Add metrics metadata**
+
+            metric.add_metadata(key="booking_id", value="booking_id")
+
+        Parameters
+        ----------
+        name : str
+            Metadata key
+        value : any
+            Metadata value
+        """
+        logger.debug(f"Adding metadata: {key}:{value}")
+
+        # Cast key to str according to EMF spec
+        # Majority of keys are expected to be string already, so
+        # checking before casting improves performance in most cases
+        if isinstance(key, str):
+            self.metadata_set[key] = value
+        else:
+            self.metadata_set[str(key)] = value
+
     def __extract_metric_unit_value(self, unit: Union[str, MetricUnit]) -> str:
         """Return metric value from metric unit whether that's str or MetricUnit enum
 

aws_lambda_powertools/metrics/metrics.py

@@ -67,20 +67,28 @@ def do_something():
 
     _metrics = {}
     _dimensions = {}
+    _metadata = {}
 
     def __init__(self, service: str = None, namespace: str = None):
         self.metric_set = self._metrics
         self.dimension_set = self._dimensions
         self.service = service
         self.namespace = namespace
+        self.metadata_set = self._metadata
+
         super().__init__(
-            metric_set=self.metric_set, dimension_set=self.dimension_set, namespace=self.namespace, service=self.service
+            metric_set=self.metric_set,
+            dimension_set=self.dimension_set,
+            namespace=self.namespace,
+            metadata_set=self.metadata_set,
+            service=self.service,
         )
 
     def clear_metrics(self):
         logger.debug("Clearing out existing metric set from memory")
         self.metric_set.clear()
         self.dimension_set.clear()
+        self.metadata_set.clear()
 
     def log_metrics(
         self,

tests/functional/test_metrics.py

@@ -533,3 +533,30 @@ def lambda_handler(evt, ctx):
 
     for metric_record in second_output["_aws"]["CloudWatchMetrics"]:
         assert ["service"] in metric_record["Dimensions"]
+
+
+def test_add_metadata_non_string_dimension_keys(service, metric, namespace):
+    # GIVEN Metrics is initialized
+    my_metrics = Metrics(service=service, namespace=namespace)
+    my_metrics.add_metric(**metric)
+
+    # WHEN we utilize add_metadata with non-string keys
+    my_metrics.add_metadata(key=10, value="number_ten")
+
+    # THEN we should have no exceptions
+    # and dimension values should be serialized as strings
+    expected_metadata = {"10": "number_ten"}
+    assert my_metrics.metadata_set == expected_metadata
+
+
+def test_add_metadata(service, metric, namespace):
+    # GIVEN Metrics is initialized
+    my_metrics = Metrics(service=service, namespace=namespace)
+    my_metrics.add_metric(**metric)
+
+    # WHEN we utilize add_metadata with non-string keys
+    my_metrics.add_metadata(key="username", value="test")
+
+    # THEN we should have no exceptions
+    # and dimension values should be serialized as strings
+    assert my_metrics.metadata_set == {"username": "test"}