docs(metrics): Add section about adding the same metric name multiple time

Author: ijemmy

docs/core/metrics.md

@@ -132,6 +132,55 @@ You can create metrics using `addMetric`, and you can create dimensions for all
 !!! warning "Do not create metrics or dimensions outside the handler"
     Metrics or dimensions added in the global scope will only be added during cold start. Disregard if that's the intended behaviour.
 
+### Adding the same metric multiple times
+You can call `addMetric()` with the same name multiple times. The values will be grouped together in an array.
+
+=== "addMetric() with the same name"
+
+    ```typescript hl_lines="8 10"
+    import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+    import { Context } from 'aws-lambda'; 
+
+
+    const metrics = new Metrics({namespace:"serverlessAirline", service:"orders"});
+
+    export const handler = async (event: any, context: Context) => {
+        metrics.addMetric('performedActionA', MetricUnits.Count, 2);
+        // do something else...
+        metrics.addMetric('performedActionA', MetricUnits.Count, 1);
+    }
+    ```
+=== "Example CloudWatch Logs excerpt"
+
+    ```json hl_lines="15-16 23-26"
+    {
+        "successfulBooking": 1.0,
+        "_aws": {
+            "Timestamp": 1592234975665,
+            "CloudWatchMetrics": [
+                {
+                "Namespace": "serverlessAirline",
+                "Dimensions": [
+                    [
+                    "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                    "Name": "performedActionA",
+                    "Unit": "Count"
+                    }
+                ]
+                }
+            ]
+        },
+        "service": "orders",
+        "performedActionA": [
+            2,
+            1
+        ]
+    }
+    ```
 ### Adding default dimensions
 
 You can use add default dimensions to your metrics by passing them as parameters in 4 ways:  
@@ -264,23 +313,23 @@ See below an example of how to automatically flush metrics with the Middy-compat
     {
         "bookingConfirmation": 1.0,
         "_aws": {
-        "Timestamp": 1592234975665,
-        "CloudWatchMetrics": [
-            {
-            "Namespace": "exampleApplication",
-            "Dimensions": [
-                [
-                "service"
-                ]
-            ],
-            "Metrics": [
+            "Timestamp": 1592234975665,
+            "CloudWatchMetrics": [
                 {
-                "Name": "bookingConfirmation",
-                "Unit": "Count"
+                "Namespace": "exampleApplication",
+                "Dimensions": [
+                    [
+                    "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                    "Name": "bookingConfirmation",
+                    "Unit": "Count"
+                    }
+                ]
                 }
             ]
-            }
-        ]
         },
         "service": "exampleService"
     }
@@ -316,23 +365,23 @@ export class MyFunction {
     {
         "bookingConfirmation": 1.0,
         "_aws": {
-        "Timestamp": 1592234975665,
-        "CloudWatchMetrics": [
-            {
-            "Namespace": "exampleApplication",
-            "Dimensions": [
-                [
-                "service"
-                ]
-            ],
-            "Metrics": [
+            "Timestamp": 1592234975665,
+            "CloudWatchMetrics": [
                 {
-                "Name": "bookingConfirmation",
-                "Unit": "Count"
+                "Namespace": "exampleApplication",
+                "Dimensions": [
+                    [
+                    "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                    "Name": "bookingConfirmation",
+                    "Unit": "Count"
+                    }
+                ]
                 }
             ]
-            }
-        ]
         },
         "service": "exampleService"
     }
@@ -456,23 +505,23 @@ You can add high-cardinality data as part of your Metrics log with `addMetadata`
     {
         "successfulBooking": 1.0,
         "_aws": {
-        "Timestamp": 1592234975665,
-        "CloudWatchMetrics": [
-            {
-            "Namespace": "exampleApplication",
-            "Dimensions": [
-                [
-                "service"
-                ]
-            ],
-            "Metrics": [
+            "Timestamp": 1592234975665,
+            "CloudWatchMetrics": [
                 {
-                "Name": "successfulBooking",
-                "Unit": "Count"
+                "Namespace": "exampleApplication",
+                "Dimensions": [
+                    [
+                    "service"
+                    ]
+                ],
+                "Metrics": [
+                    {
+                    "Name": "successfulBooking",
+                    "Unit": "Count"
+                    }
+                ]
                 }
             ]
-            }
-        ]
         },
         "service": "booking",
         "bookingId": "7051cd10-6283-11ec-90d6-0242ac120003"