Adding examples + doc

Author: leandrodamascena

aws_lambda_powertools/metrics/base.py

@@ -557,7 +557,6 @@ def single_metric(
     resolution: MetricResolution | int = 60,
     namespace: str | None = None,
     default_dimensions: Dict[str, str] | None = None,
-    timestamp: int | datetime.datetime | None = None,
 ) -> Generator[SingleMetric, None, None]:
     """Context manager to simplify creation of a single metric
 
@@ -620,9 +619,6 @@ def single_metric(
         metric: SingleMetric = SingleMetric(namespace=namespace)
         metric.add_metric(name=name, unit=unit, value=value, resolution=resolution)
 
-        if timestamp:
-            metric.set_timestamp(timestamp)
-
         if default_dimensions:
             for dim_name, dim_value in default_dimensions.items():
                 metric.add_dimension(name=dim_name, value=dim_value)

docs/core/metrics.md

@@ -224,14 +224,15 @@ You can add high-cardinality data as part of your Metrics log with `add_metadata
     --8<-- "examples/metrics/src/add_metadata_output.json"
     ```
 
-### Single metric with a different dimension
+### Single metric
 
-CloudWatch EMF uses the same dimensions across all your metrics. Use `single_metric` if you have a metric that should have different dimensions.
+CloudWatch EMF uses the same dimensions and timestamp across all your metrics. Use `single_metric` if you have a metric that should have different dimensions or timestamp.
 
-???+ info
-    Generally, this would be an edge case since you [pay for unique metric](https://aws.amazon.com/cloudwatch/pricing){target="_blank"}. Keep the following formula in mind:
+#### Working with different dimensions
+
+Generally, using different dimensions would be an edge case since you [pay for unique metric](https://aws.amazon.com/cloudwatch/pricing){target="_blank"}.
 
-    **unique metric = (metric_name + dimension_name + dimension_value)**
+Keep the following formula in mind: **unique metric = (metric_name + dimension_name + dimension_value)**
 
 === "single_metric.py"
 
@@ -259,6 +260,22 @@ By default it will skip all previously defined dimensions including default dime
     --8<-- "examples/metrics/src/single_metric_default_dimensions.py"
     ```
 
+#### Working with different timestamp
+
+When working with multiple metrics, customers may need different timestamps between them. In such cases, utilize `single_metric` to flush individual metrics with specific timestamps.
+
+=== "single_metric_with_different_timestamp.py"
+
+    ```python hl_lines="15 17"
+    --8<-- "examples/metrics/src/single_metric_with_different_timestamp.py"
+    ```
+
+=== "single_metric_with_different_timestamp_payload.json"
+
+    ```json hl_lines="5 10 15 20 25"
+    --8<-- "examples/metrics/src/single_metric_with_different_timestamp_payload.json"
+    ```
+
 ### Flushing metrics manually
 
 If you are using the [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter){target="_blank"} project, or a middleware with custom metric logic, you can use `flush_metrics()`. This method will serialize, print metrics available to standard output, and clear in-memory metrics data.

examples/metrics/src/single_metric_with_different_timestamp.py

@@ -0,0 +1,18 @@
+from aws_lambda_powertools import Logger, single_metric
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    for record in event:
+
+        record_id: str = record.get("record_id")
+        amount: int = record.get("amount")
+        timestamp: int = record.get("timestamp")
+
+        with single_metric(name="Orders", unit=MetricUnit.Count, value=amount, namespace="Powertools") as metric:
+            logger.info(f"Processing record id {record_id}")
+            metric.set_timestamp(timestamp)

examples/metrics/src/single_metric_with_different_timestamp_payload.json

@@ -0,0 +1,27 @@
+[
+    {
+        "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+        "amount": 10,
+        "timestamp": 1648195200000
+    },
+    {
+        "record_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
+        "amount": 30,
+        "timestamp": 1648224000000
+    },
+    {
+        "record_id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
+        "amount": 25,
+        "timestamp": 1648209600000
+    },
+    {
+        "record_id": "6ba7b813-9dad-11d1-80b4-00c04fd430c8",
+        "amount": 40,
+        "timestamp": 1648177200000
+    },
+    {
+        "record_id": "6ba7b814-9dad-11d1-80b4-00c04fd430c8",
+        "amount": 32,
+        "timestamp": 1648216800000
+    }
+]

tests/functional/metrics/test_metrics_cloudwatch_emf.py

@@ -158,8 +158,8 @@ def test_single_metric_with_custom_timestamp(capsys, metric, dimension, namespac
         namespace=namespace,
         default_dimensions=default_dimensions,
         **metric,
-        timestamp=timestamp,
     ) as my_metric:
+        my_metric.set_timestamp(timestamp)
         my_metric.add_metric(name="second_metric", unit="Count", value=1)
 
     output = capture_metrics_output(capsys)