docs(metrics): Improved documentation for adding dimensions

docs/features/metrics.md

@@ -105,32 +105,57 @@ You can initialize Metrics anywhere in your code - It'll keep track of your aggr
 
 ### Creating metrics
 
-You can create metrics using the `addMetric` method, and you can create dimensions for all your aggregate metrics using the `addDimension` method.
+You can create metrics using the `addMetric` method. Metrics are automatically associated with your configured namespace and dimensions.
 
 === "Metrics"
 
     ```typescript hl_lines="12"
     --8<-- "examples/snippets/metrics/createMetrics.ts"
     ```
 
+=== "Cloudwatch Log"
+
+    ```json
+    --8<-- "examples/snippets/metrics/samples/createMetricsLog.json"
+    ```
+
+### Adding dimensions
+
+By default, Powertools adds a `service` dimension in a [DimensionSet](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html){target="_blank"}. You can append additional dimensions for all your aggregate metrics using the `addDimension` method.
+
+!!! note
+    The `addDimension` method appends the dimension to the first `DimensionSet` in the `DimensionSet` array. To create a new `DimensionSet`, use the `addDimensions` method.
+
 === "Metrics with custom dimensions"
 
     ```typescript hl_lines="12-13"
     --8<-- "examples/snippets/metrics/customDimensions.ts"
     ```
 
-### Creating dimension sets
+=== "Cloudwatch Log"
 
-You can create separate dimension sets for your metrics using the `addDimensions` method. This allows you to group metrics by different dimension combinations.
+    ```json
+    --8<-- "examples/snippets/metrics/samples/customDimensionsLog.json"
+    ```
+
+### Creating a `DimensionSet`
+
+You can create a separate `DimensionSet` 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.
+When you call `addDimensions()`, it creates a new `DimensionSet` rather than adding to the first set. 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"
+    ```typescript hl_lines="9 15-19 21-25"
     --8<-- "examples/snippets/metrics/dimensionSets.ts"
     ```
 
+=== "Cloudwatch Log"
+
+    ```json
+    --8<-- "examples/snippets/metrics/samples/dimensionSetsLog.json"
+    ```
+
 !!! 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".
 
@@ -168,32 +193,7 @@ You can call `addMetric()` with the same name multiple times. The values will be
 === "Example CloudWatch Logs excerpt"
 
     ```json hl_lines="2-5 18-19"
-    {
-        "performedActionA": [
-            2,
-            1
-        ],
-        "_aws": {
-            "Timestamp": 1592234975665,
-            "CloudWatchMetrics": [
-                {
-                "Namespace": "serverlessAirline",
-                "Dimensions": [
-                    [
-                    "service"
-                    ]
-                ],
-                "Metrics": [
-                    {
-                    "Name": "performedActionA",
-                    "Unit": "Count"
-                    }
-                ]
-                }
-            ]
-        },
-        "service": "orders"
-    }
+    --8<-- "examples/snippets/metrics/samples/multiValueMetricsLog.json"
     ```
 
 ### Adding default dimensions
@@ -278,23 +278,7 @@ See below an example of how to automatically flush metrics with the Middy-compat
 === "Example CloudWatch Logs excerpt"
 
     ```json
-    {
-        "successfulBooking": 1.0,
-        "_aws": {
-            "Timestamp": 1592234975665,
-            "CloudWatchMetrics": [{
-                "Namespace": "serverlessAirline",
-                "Dimensions": [
-                    [ "service" ]
-                ],
-                "Metrics": [{
-                    "Name": "successfulBooking",
-                    "Unit": "Count"
-                }]
-            }]
-        },
-        "service": "orders"
-    }
+    --8<-- "examples/snippets/metrics/samples/middyLog.json"
     ```
 
 #### Using the class decorator
@@ -319,23 +303,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h
 === "Example CloudWatch Logs excerpt"
 
     ```json
-    {
-        "successfulBooking": 1.0,
-        "_aws": {
-            "Timestamp": 1592234975665,
-            "CloudWatchMetrics": [{
-                "Namespace": "successfulBooking",
-                "Dimensions": [
-                    [ "service" ]
-                ],
-                "Metrics": [{
-                    "Name": "successfulBooking",
-                    "Unit": "Count"
-                }]
-            }]
-        },
-        "service": "orders"
-    }
+    --8<-- "examples/snippets/metrics/samples/decoratorLog.json"
     ```
 
 #### Manually
@@ -354,23 +322,7 @@ You can manually flush the metrics with `publishStoredMetrics` as follows:
 === "Example CloudWatch Logs excerpt"
 
     ```json
-    {
-        "successfulBooking": 1.0,
-        "_aws": {
-            "Timestamp": 1592234975665,
-            "CloudWatchMetrics": [{
-                "Namespace": "successfulBooking",
-                "Dimensions": [
-                    [ "service" ]
-                ],
-                "Metrics": [{
-                    "Name": "successfulBooking",
-                    "Unit": "Count"
-                }]
-            }]
-        },
-        "service": "orders"
-    }
+    --8<-- "examples/snippets/metrics/samples/manualLog.json"
     ```
 
 #### Throwing a RangeError when no metrics are emitted
@@ -448,30 +400,7 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad
 === "Example CloudWatch Logs excerpt"
 
     ```json hl_lines="31"
-    {
-        "successfulBooking": 1.0,
-        "_aws": {
-            "Timestamp": 1592234975665,
-            "CloudWatchMetrics": [{
-                "Namespace": "serverlessAirline",
-                "Dimensions": [
-                    [ "service" ]
-                ],
-                "Metrics": [{
-                    "Namespace": "exampleApplication",
-                    "Dimensions": [
-                        [ "service" ]
-                    ],
-                    "Metrics": [{
-                        "Name": "successfulBooking",
-                        "Unit": "Count"
-                    }]
-                }]
-            }]
-        },
-        "service": "orders",
-        "bookingId": "7051cd10-6283-11ec-90d6-0242ac120003"
-    }
+    --8<-- "examples/snippets/metrics/samples/addMetadataLog.json"
     ```
 
 ### Single metric with different dimensions

examples/snippets/metrics/samples/addMetadataLog.json

@@ -0,0 +1,26 @@
+{
+  "successfulBooking": 1.0,
+  "_aws": {
+    "Timestamp": 1592234975665,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "serverlessAirline",
+        "Dimensions": [["service"]],
+        "Metrics": [
+          {
+            "Namespace": "exampleApplication",
+            "Dimensions": [["service"]],
+            "Metrics": [
+              {
+                "Name": "successfulBooking",
+                "Unit": "Count"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders",
+  "bookingId": "7051cd10-6283-11ec-90d6-0242ac120003"
+}

examples/snippets/metrics/samples/createMetricsLog.json

@@ -0,0 +1,19 @@
+{
+  "_aws": {
+    "Timestamp": 1763409658885,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "serverlessAirline",
+        "Dimensions": [["service"]],
+        "Metrics": [
+          {
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders",
+  "successfulBooking": 1
+}

examples/snippets/metrics/samples/customDimensionsLog.json

@@ -0,0 +1,20 @@
+{
+  "_aws": {
+    "Timestamp": 1763409658885,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "serverlessAirline",
+        "Dimensions": [["service", "environment"]],
+        "Metrics": [
+          {
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders",
+  "environment": "prod",
+  "successfulBooking": 1
+}

examples/snippets/metrics/samples/decoratorLog.json

@@ -0,0 +1,19 @@
+{
+  "successfulBooking": 1.0,
+  "_aws": {
+    "Timestamp": 1592234975665,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "successfulBooking",
+        "Dimensions": [["service"]],
+        "Metrics": [
+          {
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders"
+}

examples/snippets/metrics/samples/dimensionSetsLog.json

@@ -0,0 +1,28 @@
+{
+  "_aws": {
+    "Timestamp": 1763409658885,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "serverlessAirline",
+        "Dimensions": [
+          ["service", "environment"],
+          ["dimension1", "dimension2"],
+          ["region", "category"]
+        ],
+        "Metrics": [
+          {
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders",
+  "environment": "prod",
+  "dimension1": "1",
+  "dimension2": "2",
+  "region": "us-east-1",
+  "category": "books",
+  "successfulBooking": 1
+}

examples/snippets/metrics/samples/manualLog.json

@@ -0,0 +1,19 @@
+{
+  "successfulBooking": 1.0,
+  "_aws": {
+    "Timestamp": 1592234975665,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "successfulBooking",
+        "Dimensions": [["service"]],
+        "Metrics": [
+          {
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders"
+}

examples/snippets/metrics/samples/middyLog.json

@@ -0,0 +1,19 @@
+{
+  "successfulBooking": 1.0,
+  "_aws": {
+    "Timestamp": 1592234975665,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "serverlessAirline",
+        "Dimensions": [["service"]],
+        "Metrics": [
+          {
+            "Name": "successfulBooking",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders"
+}

examples/snippets/metrics/samples/multiValueMetricsLog.json

@@ -0,0 +1,19 @@
+{
+  "performedActionA": [2, 1],
+  "_aws": {
+    "Timestamp": 1592234975665,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "serverlessAirline",
+        "Dimensions": [["service"]],
+        "Metrics": [
+          {
+            "Name": "performedActionA",
+            "Unit": "Count"
+          }
+        ]
+      }
+    ]
+  },
+  "service": "orders"
+}