Add support for setTimestamp.

Author: phipag

powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/Metrics.java

@@ -15,6 +15,7 @@
 package software.amazon.lambda.powertools.metrics;
 
 import com.amazonaws.services.lambda.runtime.Context;
+import java.time.Instant;
 
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
 import software.amazon.lambda.powertools.metrics.model.MetricResolution;
@@ -76,6 +77,13 @@ default void addDimension(String key, String value) {
      */
     void addDimension(DimensionSet dimensionSet);
 
+    /**
+     * Set a custom timestamp for the metrics
+     *
+     * @param timestamp the timestamp to use for the metrics
+     */
+    void setTimestamp(Instant timestamp);
+
     /**
      * Add metadata
      *

powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLogger.java

@@ -17,6 +17,7 @@
 import static software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor.getXrayTraceId;
 import static software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor.isColdStart;
 
+import java.time.Instant;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -135,6 +136,13 @@ public void setRaiseOnEmptyMetrics(boolean raiseOnEmptyMetrics) {
         this.raiseOnEmptyMetrics = raiseOnEmptyMetrics;
     }
 
+    @Override
+    public void setTimestamp(Instant timestamp) {
+        Validator.validateTimestamp(timestamp);
+
+        emfLogger.setTimestamp(timestamp);
+    }
+
     @Override
     public void clearDefaultDimensions() {
         emfLogger.resetDimensions(false);

powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/internal/Validator.java

@@ -14,6 +14,9 @@
 
 package software.amazon.lambda.powertools.metrics.internal;
 
+import java.time.Instant;
+import java.util.concurrent.TimeUnit;
+
 import org.apache.commons.lang3.StringUtils;
 
 /**
@@ -24,6 +27,8 @@ public class Validator {
     private static final int MAX_DIMENSION_VALUE_LENGTH = 1024;
     private static final int MAX_NAMESPACE_LENGTH = 255;
     private static final String NAMESPACE_REGEX = "^[a-zA-Z0-9._#/]+$";
+    public static final long MAX_TIMESTAMP_PAST_AGE_SECONDS = TimeUnit.DAYS.toSeconds(14);
+    public static final long MAX_TIMESTAMP_FUTURE_AGE_SECONDS = TimeUnit.HOURS.toSeconds(2);
 
     private Validator() {
         // Private constructor to prevent instantiation
@@ -50,6 +55,37 @@ public static void validateNamespace(String namespace) {
         }
     }
 
+    /**
+     * Validates Timestamp.
+     *
+     * @see <a
+     *     href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#about_timestamp">CloudWatch
+     *     Timestamp</a>
+     * @param timestamp Timestamp
+     * @throws IllegalArgumentException if timestamp is invalid
+     */
+    public static void validateTimestamp(Instant timestamp) {
+        if (timestamp == null) {
+            throw new IllegalArgumentException("Timestamp cannot be null");
+        }
+
+        if (timestamp.isAfter(
+                Instant.now().plusSeconds(MAX_TIMESTAMP_FUTURE_AGE_SECONDS))) {
+            throw new IllegalArgumentException(
+                    "Timestamp cannot be more than "
+                            + MAX_TIMESTAMP_FUTURE_AGE_SECONDS
+                            + " seconds in the future");
+        }
+
+        if (timestamp.isBefore(
+                Instant.now().minusSeconds(MAX_TIMESTAMP_PAST_AGE_SECONDS))) {
+            throw new IllegalArgumentException(
+                    "Timestamp cannot be more than "
+                            + MAX_TIMESTAMP_PAST_AGE_SECONDS
+                            + " seconds in the past");
+        }
+    }
+
     /**
      * Validates a dimension key-value pair.
      *

powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLoggerTest.java

@@ -23,6 +23,7 @@
 import java.lang.reflect.Method;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
+import java.time.Instant;
 import java.util.stream.Stream;
 
 import org.junit.jupiter.api.AfterEach;
@@ -187,6 +188,25 @@ void shouldAddDimension() throws Exception {
         assertThat(hasDimension).isTrue();
     }
 
+    @Test
+    void shouldSetCustomTimestamp() throws Exception {
+        // Given
+        Instant customTimestamp = Instant.now();
+
+        // When
+        metrics.setTimestamp(customTimestamp);
+        metrics.addMetric("test-metric", 100);
+        metrics.flush();
+
+        // Then
+        String emfOutput = outputStreamCaptor.toString().trim();
+        JsonNode rootNode = objectMapper.readTree(emfOutput);
+
+        assertThat(rootNode.has("_aws")).isTrue();
+        assertThat(rootNode.get("_aws").has("Timestamp")).isTrue();
+        assertThat(rootNode.get("_aws").get("Timestamp").asLong()).isEqualTo(customTimestamp.toEpochMilli());
+    }
+
     @Test
     void shouldAddDimensionSet() throws Exception {
         // Given

powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/ValidatorTest.java

@@ -17,6 +17,8 @@
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
+import java.time.Instant;
+
 import org.junit.jupiter.api.Test;
 
 class ValidatorTest {
@@ -177,4 +179,46 @@ void shouldAcceptValidDimension() {
         assertThatCode(() -> Validator.validateDimension("ValidKey", "ValidValue"))
                 .doesNotThrowAnyException();
     }
+
+    @Test
+    void shouldThrowExceptionWhenTimestampIsNull() {
+        // When/Then
+        assertThatThrownBy(() -> Validator.validateTimestamp(null))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessage("Timestamp cannot be null");
+    }
+
+    @Test
+    void shouldThrowExceptionWhenTimestampIsTooFarInFuture() {
+        // Given
+        Instant futureTooFar = Instant.now().plusSeconds(Validator.MAX_TIMESTAMP_FUTURE_AGE_SECONDS + 1);
+
+        // When/Then
+        assertThatThrownBy(() -> Validator.validateTimestamp(futureTooFar))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessage("Timestamp cannot be more than " + Validator.MAX_TIMESTAMP_FUTURE_AGE_SECONDS
+                        + " seconds in the future");
+    }
+
+    @Test
+    void shouldThrowExceptionWhenTimestampIsTooFarInPast() {
+        // Given
+        Instant pastTooFar = Instant.now().minusSeconds(Validator.MAX_TIMESTAMP_PAST_AGE_SECONDS + 1);
+
+        // When/Then
+        assertThatThrownBy(() -> Validator.validateTimestamp(pastTooFar))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessage("Timestamp cannot be more than " + Validator.MAX_TIMESTAMP_PAST_AGE_SECONDS
+                        + " seconds in the past");
+    }
+
+    @Test
+    void shouldAcceptValidTimestamp() {
+        // Given
+        Instant validTimestamp = Instant.now();
+
+        // When/Then
+        assertThatCode(() -> Validator.validateTimestamp(validTimestamp))
+                .doesNotThrowAnyException();
+    }
 }

powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/testutils/TestMetrics.java

@@ -1,5 +1,6 @@
 package software.amazon.lambda.powertools.metrics.testutils;
 
+import java.time.Instant;
 import java.util.Collections;
 
 import com.amazonaws.services.lambda.runtime.Context;
@@ -61,6 +62,11 @@ public void clearDefaultDimensions() {
         // Test placeholder
     }
 
+    @Override
+    public void setTimestamp(Instant timestamp) {
+        // Test placeholder
+    }
+
     @Override
     public void captureColdStartMetric(Context context, DimensionSet dimensions) {
         // Test placeholder