docs: update metrics documentation to explain addDimensions() behavior for issue #3777

Author: matteofigus

docs/features/metrics.md

@@ -119,6 +119,18 @@ You can create metrics using the `addMetric` method, and you can create dimensio
     --8<-- "examples/snippets/metrics/customDimensions.ts"
     ```
 
+### Creating dimension sets
+
+You can create separate dimension sets for your metrics using the `addDimensions` method. This allows you to group metrics by different dimension combinations.
+
+When you call `addDimensions()`, it creates a new dimension set rather than adding to the existing dimensions. This is useful when you want to track the same metric across different dimension combinations.
+
+=== "handler.ts"
+
+    ```typescript hl_lines="9 12-15 18-21"
+    --8<-- "examples/snippets/metrics/dimensionSets.ts"
+    ```
+
 !!! tip "Autocomplete Metric Units"
     Use the `MetricUnit` enum to easily find a supported metric unit by CloudWatch. Alternatively, you can pass the value as a string if you already know them e.g. "Count".
 

examples/snippets/metrics/dimensionSets.ts

@@ -0,0 +1,30 @@
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
+
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
+
+export const handler = async (
+  _event: unknown,
+  _context: unknown
+): Promise<void> => {
+  // Add a single dimension
+  metrics.addDimension('environment', 'prod');
+
+  // Add a new dimension set
+  metrics.addDimensions({
+    dimension1: '1',
+    dimension2: '2',
+  });
+
+  // Add another dimension set
+  metrics.addDimensions({
+    region: 'us-east-1',
+    category: 'books',
+  });
+
+  // Add metrics
+  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+  metrics.publishStoredMetrics();
+};