fix(metrics): addDimensions() documentation and tests

docs/features/metrics.md

@@ -502,3 +502,43 @@ When `POWERTOOLS_DEV` is enabled, Metrics uses the global `console` to emit metr
     ```typescript hl_lines="4-5 12"
     --8<-- "examples/snippets/metrics/testingMetrics.ts"
     ```
+
+## Multiple dimension sets
+
+You can create multiple dimension sets for your metrics using the `addDimensions` or `addDimensionSet` methods. This allows you to aggregate metrics across various dimensions, providing more granular insights into your application.
+
+=== "Creating multiple dimension sets"
+
+    ```typescript hl_lines="10-25"
+    --8<-- "examples/snippets/metrics/multiDimensionSets.ts"
+    ```
+
+=== "Example CloudWatch Logs excerpt"
+
+    ```json
+    {
+      "successfulBooking": 1.0,
+      "_aws": {
+        "Timestamp": 1592234975665,
+        "CloudWatchMetrics": [{
+          "Namespace": "serverlessAirline",
+          "Dimensions": [
+            ["service", "environment", "region"],
+            ["service", "dimension1", "dimension2"],
+            ["service", "feature", "version"]
+          ],
+          "Metrics": [{
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }]
+        }]
+      },
+      "service": "orders",
+      "environment": "prod",
+      "region": "us-west-2",
+      "dimension1": "1",
+      "dimension2": "2",
+      "feature": "booking",
+      "version": "v1"
+    }
+    ```

examples/snippets/metrics/multiDimensionSets.ts

@@ -0,0 +1,28 @@
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
+
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+  defaultDimensions: { environment: 'prod' },
+});
+
+export const handler = async () => {
+  // Add a single dimension to the default dimension set
+  metrics.addDimension('region', 'us-west-2');
+
+  // Add a new dimension set
+  metrics.addDimensions({
+    dimension1: '1',
+    dimension2: '2',
+  });
+
+  // Add another dimension set (addDimensionSet is an alias for addDimensions)
+  metrics.addDimensionSet({
+    feature: 'booking',
+    version: 'v1',
+  });
+
+  // This will create three dimension sets in the EMF output
+  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+  metrics.publishStoredMetrics();
+};

packages/metrics/src/Metrics.ts

@@ -255,15 +255,39 @@ class Metrics extends Utility implements MetricsInterface {
   }
 
   /**
-   * Add multiple dimensions to the metrics.
+   * Add multiple dimensions to the metrics as a new dimension set.
    *
-   * This method is useful when you want to add multiple dimensions to the metrics at once.
+   * This method creates a new dimension set that will be included in the EMF output.
    * Invalid dimension values are skipped and a warning is logged.
    *
    * When calling the {@link Metrics.publishStoredMetrics | `publishStoredMetrics()`} method, the dimensions are cleared. This type of
    * dimension is useful when you want to add request-specific dimensions to your metrics. If you want to add dimensions that are
    * included in all metrics, use the {@link Metrics.setDefaultDimensions | `setDefaultDimensions()`} method.
    *
+   * @example
+   * ```typescript
+   * import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';
+   *
+   * const metrics = new Metrics({
+   *   namespace: 'serverlessAirline',
+   *   serviceName: 'orders',
+   * });
+   *
+   * // Add a single dimension
+   * metrics.addDimension('environment', 'prod');
+   *
+   * // Add a new dimension set
+   * metrics.addDimensions({
+   *   dimension1: "1",
+   *   dimension2: "2"
+   * });
+   *
+   * // This will create two dimension sets in the EMF output:
+   * // [["service", "environment"]] and [["service", "dimension1", "dimension2"]]
+   * metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+   * metrics.publishStoredMetrics();
+   * ```
+   *
    * @param dimensions - An object with key-value pairs of dimensions
    */
   public addDimensions(dimensions: Dimensions): void {
@@ -272,6 +296,17 @@ class Metrics extends Utility implements MetricsInterface {
     }
   }
 
+  /**
+   * Add a dimension set to metrics.
+   *
+   * This is an alias for {@link Metrics.addDimensions | `addDimensions()`} for consistency with other Powertools for AWS Lambda implementations.
+   *
+   * @param dimensions - An object with key-value pairs of dimensions
+   */
+  public addDimensionSet(dimensions: Dimensions): void {
+    this.addDimensions(dimensions);
+  }
+
   /**
    * A metadata key-value pair to be included with metrics.
    *
@@ -692,7 +727,8 @@ class Metrics extends Utility implements MetricsInterface {
       {}
     );
 
-    const dimensionNames = [
+    // Create the default dimension set from default dimensions and current dimensions
+    const defaultDimensionNames = [
       ...new Set([
         ...Object.keys(this.defaultDimensions),
         ...Object.keys(this.dimensions),
@@ -705,7 +741,7 @@ class Metrics extends Utility implements MetricsInterface {
         CloudWatchMetrics: [
           {
             Namespace: this.namespace || DEFAULT_NAMESPACE,
-            Dimensions: [dimensionNames],
+            Dimensions: [defaultDimensionNames],
             Metrics: metricDefinitions,
           },
         ],