adding docs + small refactor

Author: leandrodamascena

aws_lambda_powertools/metrics/metrics.py

@@ -123,12 +123,12 @@ def add_metric(
     def add_dimension(self, name: str, value: str) -> None:
         self.provider.add_dimension(name=name, value=value)
 
-    def add_dimensions(self, dimensions: dict[str, str]) -> None:
+    def add_dimensions(self, **dimensions: str) -> None:
         """Add a new set of dimensions creating an additional dimension array.
 
         Creates a new dimension set in the CloudWatch EMF Dimensions array.
         """
-        self.provider.add_dimensions(dimensions=dimensions)
+        self.provider.add_dimensions(**dimensions)
 
     def serialize_metric_set(
         self,

aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py

@@ -326,10 +326,21 @@ def add_dimension(self, name: str, value: str) -> None:
 
         self.dimension_set[name] = value
 
-    def add_dimensions(self, dimensions: dict[str, str]) -> None:
+    def add_dimensions(self, **dimensions: str) -> None:
         """Add a new set of dimensions creating an additional dimension array.
 
         Creates a new dimension set in the CloudWatch EMF Dimensions array.
+
+        Example
+        -------
+        **Add multiple dimension sets**
+
+            metrics.add_dimensions(environment="prod", region="us-east-1")
+
+        Parameters
+        ----------
+        dimensions : str
+            Dimension key-value pairs as keyword arguments
         """
         logger.debug(f"Adding dimension set: {dimensions}")
 
@@ -341,11 +352,21 @@ def add_dimensions(self, dimensions: dict[str, str]) -> None:
             )
             return
 
-        # Convert values to strings and validate
+        sanitized = self._sanitize_dimensions(dimensions)
+        if not sanitized:
+            return
+
+        self._validate_dimension_limit(sanitized)
+
+        self.dimension_sets.append({**self.default_dimensions, **sanitized})
+
+    def _sanitize_dimensions(self, dimensions: dict[str, str]) -> dict[str, str]:
+        """Convert dimension values to strings and filter out empty ones."""
         sanitized: dict[str, str] = {}
+
         for name, value in dimensions.items():
-            str_value = value if isinstance(value, str) else str(value)
-            str_name = name if isinstance(name, str) else str(name)
+            str_name = str(name)
+            str_value = str(value)
 
             if not str_name.strip() or not str_value.strip():
                 warnings.warn(
@@ -357,24 +378,18 @@ def add_dimensions(self, dimensions: dict[str, str]) -> None:
 
             sanitized[str_name] = str_value
 
-        if not sanitized:
-            return
+        return sanitized
 
-        # Count unique dimensions across all sets
+    def _validate_dimension_limit(self, new_dimensions: dict[str, str]) -> None:
+        """Validate that adding new dimensions won't exceed CloudWatch limits."""
         all_keys = set(self.dimension_set.keys())
         for ds in self.dimension_sets:
             all_keys.update(ds.keys())
-        all_keys.update(sanitized.keys())
+        all_keys.update(new_dimensions.keys())
 
         if len(all_keys) > MAX_DIMENSIONS:
             raise SchemaValidationError(f"Maximum dimensions ({MAX_DIMENSIONS}) exceeded")
 
-        # Add default dimensions to this set
-        with_defaults = dict(self.default_dimensions)
-        with_defaults.update(sanitized)
-
-        self.dimension_sets.append(with_defaults)
-
     def add_metadata(self, key: str, value: Any) -> None:
         """Adds high cardinal metadata for metrics object
 

docs/core/metrics.md

@@ -22,7 +22,7 @@ If you're new to Amazon CloudWatch, there are five terminologies you must be awa
 * **Dimensions**. Metrics metadata in key-value format. They help you slice and dice metrics visualization, for example `ColdStart` metric by Payment `service`.
 * **Metric**. It's the name of the metric, for example: `SuccessfulBooking` or `UpdatedBooking`.
 * **Unit**. It's a value representing the unit of measure for the corresponding metric, for example: `Count` or `Seconds`.
-* **Resolution**. It's a value representing the storage resolution for the corresponding metric. Metrics can be either Standard or High resolution. Read more [here](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/publishingMetrics.html#high-resolution-metrics){target="_blank"}.
+* **Resolution**. It's a value representing the storage resolution for the corresponding metric. Metrics can be either Standard or High resolution. Read more in the [high-resolution metrics documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/publishingMetrics.html#high-resolution-metrics){target="_blank"}.
 
 <figure>
   <img src="../../media/metrics_terminology.png" alt="Terminology" />
@@ -136,6 +136,27 @@ If you'd like to remove them at some point, you can use `clear_default_dimension
 
 **Note:** Dimensions with empty values will not be included.
 
+### Adding multiple dimension sets
+
+You can use `add_dimensions` method to create multiple dimension sets in a single EMF blob. This allows you to aggregate metrics across different dimension combinations without emitting separate metric blobs.
+
+Each call to `add_dimensions` creates a new dimension array in the CloudWatch EMF output, enabling different views of the same metric data.
+
+=== "add_dimensions.py"
+
+    ```python hl_lines="12-13"
+    --8<-- "examples/metrics/src/add_dimensions.py"
+    ```
+
+=== "add_dimensions_output.json"
+
+    ```json hl_lines="8-12"
+    --8<-- "examples/metrics/src/add_dimensions_output.json"
+    ```
+
+???+ tip "When to use multiple dimension sets"
+    Use `add_dimensions` when you need to query the same metric with different dimension combinations. For example, you might want to see `SuccessfulBooking` aggregated by `environment` alone, or by both `environment` and `region`.
+
 ### Changing default timestamp
 
 When creating metrics, we use the current timestamp. If you want to change the timestamp of all the metrics you create, utilize the `set_timestamp` function. You can specify a datetime object or an integer representing an epoch timestamp in milliseconds.
@@ -233,12 +254,12 @@ The priority of the `function_name` dimension value is defined as:
 
 The following environment variable is available to configure Metrics at a global scope:
 
-| Setting            | Description                                                  | Environment variable               | Default |
-| ------------------ | ------------------------------------------------------------ | ---------------------------------- | ------- |
-| **Namespace Name** | Sets **namespace** used for metrics.                             | `POWERTOOLS_METRICS_NAMESPACE`     | `None`  |
-| **Service**        | Sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME`      | `None`             |
-| **Function Name**  | Function name used as dimension for the **ColdStart** metric.  | `POWERTOOLS_METRICS_FUNCTION_NAME` | `None`  |
-| **Disable Powertools Metrics**  | **Disables** all metrics emitted by Powertools.	    | `POWERTOOLS_METRICS_DISABLED`      | `None`  |
+| Setting                        | Description                                                         | Environment variable               | Default |
+| ------------------------------ | ------------------------------------------------------------------- | ---------------------------------- | ------- |
+| **Namespace Name**             | Sets **namespace** used for metrics.                                | `POWERTOOLS_METRICS_NAMESPACE`     | `None`  |
+| **Service**                    | Sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME`          | `None`  |
+| **Function Name**              | Function name used as dimension for the **ColdStart** metric.       | `POWERTOOLS_METRICS_FUNCTION_NAME` | `None`  |
+| **Disable Powertools Metrics** | **Disables** all metrics emitted by Powertools.                     | `POWERTOOLS_METRICS_DISABLED`      | `None`  |
 
 `POWERTOOLS_METRICS_NAMESPACE` is also available on a per-instance basis with the `namespace` parameter, which will consequently override the environment variable value.
 
@@ -393,8 +414,8 @@ We provide a thin-wrapper on top of the most requested observability providers.
 
 Current providers:
 
-| Provider                              | Notes                                                    |
-| ------------------------------------- | -------------------------------------------------------- |
+| Provider                                 | Notes                                                    |
+| ---------------------------------------- | -------------------------------------------------------- |
 | [Datadog](./datadog.md){target="_blank"} | Uses Datadog SDK and Datadog Lambda Extension by default |
 
 ## Testing your code

examples/metrics/src/add_dimensions.py

@@ -0,0 +1,17 @@
+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):
+    # Add primary dimension
+    metrics.add_dimension(name="service", value="booking")
+
+    # Add multiple dimension sets for different aggregation views
+    metrics.add_dimensions(environment="prod", region="us-east-1")
+    metrics.add_dimensions(environment="prod")
+
+    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

examples/metrics/src/add_dimensions_output.json

@@ -0,0 +1,25 @@
+{
+    "_aws": {
+        "Timestamp": 1656620400000,
+        "CloudWatchMetrics": [
+            {
+                "Namespace": "ServerlessAirline",
+                "Dimensions": [
+                    ["service"],
+                    ["environment", "region"],
+                    ["environment"]
+                ],
+                "Metrics": [
+                    {
+                        "Name": "SuccessfulBooking",
+                        "Unit": "Count"
+                    }
+                ]
+            }
+        ]
+    },
+    "service": "booking",
+    "environment": "prod",
+    "region": "us-east-1",
+    "SuccessfulBooking": [1.0]
+}

tests/functional/metrics/test_dimension_sets.py

@@ -18,9 +18,9 @@ def test_add_dimensions_creates_multiple_dimension_sets(capsys):
 
     # WHEN we add multiple dimension sets
     metrics.add_dimension(name="service", value="booking")
-    metrics.add_dimensions({"environment": "prod", "region": "us-east-1"})
-    metrics.add_dimensions({"environment": "prod"})
-    metrics.add_dimensions({"region": "us-east-1"})
+    metrics.add_dimensions(environment="prod", region="us-east-1")
+    metrics.add_dimensions(environment="prod")
+    metrics.add_dimensions(region="us-east-1")
     metrics.add_metric(name="SuccessfulRequests", unit=MetricUnit.Count, value=10)
 
     # THEN the serialized output should contain multiple dimension arrays
@@ -50,8 +50,8 @@ def test_add_dimensions_with_metrics_wrapper(capsys):
     # WHEN we use add_dimensions through the Metrics wrapper
     @metrics.log_metrics
     def handler(event, context):
-        metrics.add_dimensions({"environment": "staging", "region": "us-west-2"})
-        metrics.add_dimensions({"environment": "staging"})
+        metrics.add_dimensions(environment="staging", region="us-west-2")
+        metrics.add_dimensions(environment="staging")
         metrics.add_metric(name="PaymentProcessed", unit=MetricUnit.Count, value=1)
 
     handler({}, {})
@@ -76,8 +76,8 @@ def test_add_dimensions_with_default_dimensions():
     metrics.set_default_dimensions(tenant_id="123", application="api")
 
     # WHEN we add dimension sets after setting defaults
-    metrics.add_dimensions({"environment": "prod"})
-    metrics.add_dimensions({"region": "eu-west-1"})
+    metrics.add_dimensions(environment="prod")
+    metrics.add_dimensions(region="eu-west-1")
     metrics.add_metric(name="ApiCalls", unit=MetricUnit.Count, value=5)
 
     # THEN default dimensions should be included in all dimension sets
@@ -100,9 +100,9 @@ def test_add_dimensions_duplicate_keys_last_value_wins():
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
     # WHEN we add dimension sets with duplicate keys
-    metrics.add_dimensions({"environment": "dev", "region": "us-east-1"})
-    metrics.add_dimensions({"environment": "staging", "region": "us-west-2"})
-    metrics.add_dimensions({"environment": "prod"})  # Last value for environment
+    metrics.add_dimensions(environment="dev", region="us-east-1")
+    metrics.add_dimensions(environment="staging", region="us-west-2")
+    metrics.add_dimensions(environment="prod")  # Last value for environment
     metrics.add_metric(name="TestMetric", unit=MetricUnit.Count, value=1)
 
     # THEN the last value should be used in the root
@@ -113,13 +113,13 @@ def test_add_dimensions_duplicate_keys_last_value_wins():
     assert output["region"] == "us-west-2"
 
 
-def test_add_dimensions_empty_dict_warns():
+def test_add_dimensions_empty_kwargs_warns():
     # GIVEN metrics instance
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
-    # WHEN we add an empty dimensions dict
+    # WHEN we call add_dimensions without arguments
     with pytest.warns(UserWarning, match="Empty dimensions dictionary"):
-        metrics.add_dimensions({})
+        metrics.add_dimensions()
 
     # THEN no dimension set should be added
     assert len(metrics.dimension_sets) == 0
@@ -129,9 +129,9 @@ def test_add_dimensions_invalid_dimensions_skipped():
     # GIVEN metrics instance
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
-    # WHEN we add dimensions with empty names or values
+    # WHEN we add dimensions with empty values
     with pytest.warns(UserWarning, match="empty name or value"):
-        metrics.add_dimensions({"": "value", "key": ""})
+        metrics.add_dimensions(key="")
 
     # THEN no dimension set should be added
     assert len(metrics.dimension_sets) == 0
@@ -148,15 +148,15 @@ def test_add_dimensions_exceeds_max_dimensions():
     # WHEN we try to add dimension set that would exceed max
     # THEN it should raise SchemaValidationError
     with pytest.raises(SchemaValidationError, match="Maximum dimensions"):
-        metrics.add_dimensions({"extra1": "val1", "extra2": "val2"})
+        metrics.add_dimensions(extra1="val1", extra2="val2")
 
 
 def test_add_dimensions_converts_values_to_strings():
     # GIVEN metrics instance
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
-    # WHEN we add dimensions with non-string values
-    metrics.add_dimensions({"count": 123, "is_active": True, "ratio": 3.14})
+    # WHEN we add dimensions with non-string values (using **dict for non-string values)
+    metrics.add_dimensions(**{"count": 123, "is_active": True, "ratio": 3.14})
     metrics.add_metric(name="TestMetric", unit=MetricUnit.Count, value=1)
 
     # THEN values should be converted to strings
@@ -172,8 +172,8 @@ def test_clear_metrics_clears_dimension_sets(capsys):
 
     @metrics.log_metrics
     def handler(event, context):
-        metrics.add_dimensions({"environment": "prod"})
-        metrics.add_dimensions({"region": "us-east-1"})
+        metrics.add_dimensions(environment="prod")
+        metrics.add_dimensions(region="us-east-1")
         metrics.add_metric(name="Requests", unit=MetricUnit.Count, value=1)
 
     handler({}, {})
@@ -189,9 +189,9 @@ def test_add_dimensions_order_preserved():
 
     # WHEN we add dimension sets in specific order
     metrics.add_dimension(name="service", value="api")
-    metrics.add_dimensions({"environment": "prod", "region": "us-east-1"})
-    metrics.add_dimensions({"environment": "prod"})
-    metrics.add_dimensions({"region": "us-east-1"})
+    metrics.add_dimensions(environment="prod", region="us-east-1")
+    metrics.add_dimensions(environment="prod")
+    metrics.add_dimensions(region="us-east-1")
     metrics.add_metric(name="TestMetric", unit=MetricUnit.Count, value=1)
 
     # THEN dimension sets should appear in order added
@@ -209,7 +209,7 @@ def test_add_dimensions_with_metadata():
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
     # WHEN we add dimension sets and metadata
-    metrics.add_dimensions({"environment": "prod"})
+    metrics.add_dimensions(environment="prod")
     metrics.add_metadata(key="request_id", value="abc-123")
     metrics.add_metric(name="ApiLatency", unit=MetricUnit.Milliseconds, value=150)
 
@@ -227,8 +227,8 @@ def test_multiple_metrics_with_dimension_sets():
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
     # WHEN we add multiple metrics with dimension sets
-    metrics.add_dimensions({"environment": "prod", "region": "us-east-1"})
-    metrics.add_dimensions({"environment": "prod"})
+    metrics.add_dimensions(environment="prod", region="us-east-1")
+    metrics.add_dimensions(environment="prod")
     metrics.add_metric(name="SuccessCount", unit=MetricUnit.Count, value=100)
     metrics.add_metric(name="ErrorCount", unit=MetricUnit.Count, value=5)
     metrics.add_metric(name="Latency", unit=MetricUnit.Milliseconds, value=250)
@@ -249,7 +249,7 @@ def test_add_dimensions_with_high_resolution_metrics():
     metrics = AmazonCloudWatchEMFProvider(namespace="TestApp")
 
     # WHEN we add dimension sets with high-resolution metrics
-    metrics.add_dimensions({"function": "process_order"})
+    metrics.add_dimensions(function="process_order")
     metrics.add_metric(
         name="ProcessingTime",
         unit=MetricUnit.Milliseconds,