Rename @metrics to @FlushMetrics.

phipag · phipag · commit e4a3464fdbdb · 2025-06-05T14:36:56.000+02:00
diff --git a/docs/core/metrics.md b/docs/core/metrics.md
diff --git a/examples/powertools-examples-core-utilities/cdk/app/src/main/java/helloworld/App.java b/examples/powertools-examples-core-utilities/cdk/app/src/main/java/helloworld/App.java
@@ -31,7 +31,7 @@
 import org.slf4j.LoggerFactory;
 import org.slf4j.MDC;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -49,7 +49,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
diff --git a/examples/powertools-examples-core-utilities/cdk/app/src/main/java/helloworld/AppStream.java b/examples/powertools-examples-core-utilities/cdk/app/src/main/java/helloworld/AppStream.java
@@ -26,7 +26,7 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 
 import java.io.InputStreamReader;
 import java.io.BufferedReader;
@@ -40,7 +40,7 @@ public class AppStream implements RequestStreamHandler {
 
     @Override
     @Logging(logEvent = true)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     // RequestStreamHandler can be used instead of RequestHandler for cases when you'd like to deserialize request body or serialize response body yourself, instead of allowing that to happen automatically
     // Note that you still need to return a proper JSON for API Gateway to handle 
     // See Lambda Response format for examples: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
diff --git a/examples/powertools-examples-core-utilities/gradle/src/main/java/helloworld/App.java b/examples/powertools-examples-core-utilities/gradle/src/main/java/helloworld/App.java
@@ -32,7 +32,7 @@
 import org.slf4j.LoggerFactory;
 import org.slf4j.MDC;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -50,7 +50,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
diff --git a/examples/powertools-examples-core-utilities/gradle/src/main/java/helloworld/AppStream.java b/examples/powertools-examples-core-utilities/gradle/src/main/java/helloworld/AppStream.java
@@ -26,7 +26,7 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 
 import java.io.InputStreamReader;
 import java.io.BufferedReader;
@@ -40,7 +40,7 @@ public class AppStream implements RequestStreamHandler {
 
     @Override
     @Logging(logEvent = true)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     // RequestStreamHandler can be used instead of RequestHandler for cases when you'd like to deserialize request body or serialize response body yourself, instead of allowing that to happen automatically
     // Note that you still need to return a proper JSON for API Gateway to handle 
     // See Lambda Response format for examples: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
diff --git a/examples/powertools-examples-core-utilities/kotlin/src/main/kotlin/helloworld/App.kt b/examples/powertools-examples-core-utilities/kotlin/src/main/kotlin/helloworld/App.kt
@@ -44,7 +44,7 @@ class App : RequestHandler<APIGatewayProxyRequestEvent?, APIGatewayProxyResponse
     
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     override fun handleRequest(input: APIGatewayProxyRequestEvent?, context: Context?): APIGatewayProxyResponseEvent {
         val headers = mapOf("Content-Type" to "application/json", "X-Custom-Header" to "application/json")
         
diff --git a/examples/powertools-examples-core-utilities/kotlin/src/main/kotlin/helloworld/AppStream.kt b/examples/powertools-examples-core-utilities/kotlin/src/main/kotlin/helloworld/AppStream.kt
@@ -24,7 +24,7 @@ import java.io.OutputStream
 
 class AppStream : RequestStreamHandler {
     @Logging(logEvent = true)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     @Throws(IOException::class)
     override fun handleRequest(input: InputStream, output: OutputStream, context: Context) {
         val map: Map<*, *> = mapper.readValue(input, MutableMap::class.java)
diff --git a/examples/powertools-examples-core-utilities/sam-graalvm/src/main/java/helloworld/App.java b/examples/powertools-examples-core-utilities/sam-graalvm/src/main/java/helloworld/App.java
@@ -32,7 +32,7 @@
 import org.slf4j.LoggerFactory;
 import org.slf4j.MDC;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -51,7 +51,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
diff --git a/examples/powertools-examples-core-utilities/sam/src/main/java/helloworld/App.java b/examples/powertools-examples-core-utilities/sam/src/main/java/helloworld/App.java
@@ -35,7 +35,7 @@
 import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
 
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -54,7 +54,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
diff --git a/examples/powertools-examples-core-utilities/sam/src/main/java/helloworld/AppStream.java b/examples/powertools-examples-core-utilities/sam/src/main/java/helloworld/AppStream.java
@@ -26,7 +26,7 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 
 import java.io.InputStreamReader;
 import java.io.BufferedReader;
@@ -40,7 +40,7 @@ public class AppStream implements RequestStreamHandler {
 
     @Override
     @Logging(logEvent = true)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     // RequestStreamHandler can be used instead of RequestHandler for cases when you'd like to deserialize request body or serialize response body yourself, instead of allowing that to happen automatically
     // Note that you still need to return a proper JSON for API Gateway to handle 
     // See Lambda Response format for examples: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
diff --git a/examples/powertools-examples-core-utilities/serverless/src/main/java/helloworld/App.java b/examples/powertools-examples-core-utilities/serverless/src/main/java/helloworld/App.java
@@ -32,7 +32,7 @@
 import org.apache.logging.log4j.Logger;
 import org.slf4j.MDC;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -50,7 +50,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
diff --git a/examples/powertools-examples-core-utilities/serverless/src/main/java/helloworld/AppStream.java b/examples/powertools-examples-core-utilities/serverless/src/main/java/helloworld/AppStream.java
@@ -22,14 +22,14 @@
 import java.io.OutputStream;
 import java.util.Map;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 
 public class AppStream implements RequestStreamHandler {
     private static final ObjectMapper mapper = new ObjectMapper();
 
     @Override
     @Logging(logEvent = true)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public void handleRequest(InputStream input, OutputStream output, Context context) throws IOException {
         Map map = mapper.readValue(input, Map.class);
 
diff --git a/examples/powertools-examples-core-utilities/terraform/src/main/java/helloworld/App.java b/examples/powertools-examples-core-utilities/terraform/src/main/java/helloworld/App.java
@@ -32,7 +32,7 @@
 import org.apache.logging.log4j.Logger;
 import org.slf4j.MDC;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -50,7 +50,7 @@ public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatew
 
     @Logging(logEvent = true, samplingRate = 0.7)
     @Tracing(captureMode = CaptureMode.RESPONSE_AND_ERROR)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
diff --git a/examples/powertools-examples-core-utilities/terraform/src/main/java/helloworld/AppStream.java b/examples/powertools-examples-core-utilities/terraform/src/main/java/helloworld/AppStream.java
@@ -22,14 +22,14 @@
 import java.io.OutputStream;
 import java.util.Map;
 import software.amazon.lambda.powertools.logging.Logging;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 
 public class AppStream implements RequestStreamHandler {
     private static final ObjectMapper mapper = new ObjectMapper();
 
     @Override
     @Logging(logEvent = true)
-    @Metrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
+    @FlushMetrics(namespace = "ServerlessAirline", service = "payment", captureColdStart = true)
     public void handleRequest(InputStream input, OutputStream output, Context context) throws IOException {
         Map map = mapper.readValue(input, Map.class);
 
diff --git a/powertools-e2e-tests/handlers/metrics/src/main/java/software/amazon/lambda/powertools/e2e/Function.java b/powertools-e2e-tests/handlers/metrics/src/main/java/software/amazon/lambda/powertools/e2e/Function.java
@@ -20,7 +20,7 @@
 import software.amazon.cloudwatchlogs.emf.model.DimensionSet;
 import software.amazon.cloudwatchlogs.emf.model.StorageResolution;
 import software.amazon.cloudwatchlogs.emf.model.Unit;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsUtils;
 import java.time.LocalDateTime;
 import java.time.ZoneOffset;
@@ -32,7 +32,7 @@ public class Function implements RequestHandler<Input, String> {
 
     MetricsLogger metricsLogger = MetricsUtils.metricsLogger();
 
-    @Metrics(captureColdStart = true)
+    @FlushMetrics(captureColdStart = true)
     public String handleRequest(Input input, Context context) {
 
         Instant currentTimeTruncatedPlusThirty =
@@ -49,4 +49,4 @@ public String handleRequest(Input input, Context context) {
 
         return "OK";
     }
-}
+}
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/FlushMetrics.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/FlushMetrics.java
@@ -20,45 +20,45 @@
 import java.lang.annotation.Target;
 
 /**
- * {@code Metrics} is used to signal that the annotated Lambda handler method should be
- * extended with Metrics functionality. Will have no effect when used on a method that is not a Lambda handler.
+ * {@code FlushMetrics} is used to signal that the annotated Lambda handler method should be
+ * extended with Metrics flushing functionality. Will have no effect when used on a method that is not a Lambda handler.
  *
- * <p>{@code Metrics} allows users to asynchronously create Amazon
+ * <p>{@code FlushMetrics} allows users to asynchronously create Amazon
  * CloudWatch metrics by using the CloudWatch <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html">Embedded Metrics Format</a>.
- * {@code Metrics} manages the life-cycle and configuration of the MetricsLogger to simplify the user experience when used with AWS Lambda.
+ * {@code FlushMetrics} manages the life-cycle and configuration of Metrics to simplify the user experience when used with AWS Lambda.
  *
- * <p>{@code Metrics} should be used with the handleRequest method of a class
+ * <p>{@code FlushMetrics} should be used with the handleRequest method of a class
  * which implements either
  * {@code com.amazonaws.services.lambda.runtime.RequestHandler} or
  * {@code com.amazonaws.services.lambda.runtime.RequestStreamHandler}.</p>
  *
- * <p>{@code Metrics} creates Amazon CloudWatch custom metrics. You can find
+ * <p>{@code FlushMetrics} creates Amazon CloudWatch custom metrics. You can find
  * pricing information on the <a href="https://aws.amazon.com/cloudwatch/pricing/">CloudWatch pricing documentation</a> page.</p>
  *
- * <p>To enable creation of custom metrics for cold starts you can add {@code @Metrics(captureColdStart = true)}.
+ * <p>To enable creation of custom metrics for cold starts you can add {@code @FlushMetrics(captureColdStart = true)}.
  * </br>This will create a metric with the key {@code "ColdStart"} and the unit type {@code COUNT}.
  * </p>
  *
- * <p>To raise exception if no metrics are emitted, use {@code @Metrics(raiseOnEmptyMetrics = true)}.
+ * <p>To raise exception if no metrics are emitted, use {@code @FlushMetrics(raiseOnEmptyMetrics = true)}.
  * </br>This will create an exception if no metrics are emitted. By default its value is set to false.
  * </p>
  *
  * <p>By default the service name associated with metrics created will be
  * "service_undefined". This can be overridden with the environment variable {@code POWERTOOLS_SERVICE_NAME}
- * or the annotation variable {@code @Metrics(service = "Service Name")}.
+ * or the annotation variable {@code @FlushMetrics(service = "Service Name")}.
  * If both are specified then the value of the annotation variable will be used.</p>
  *
  * <p>A namespace must be specified for metrics. This can be set with the environment variable {@code POWERTOOLS_METRICS_NAMESPACE}
- * or the annotation variable {@code @Metrics(namespace = "Namespace")}. If not specified, an IllegalStateException will be thrown.
+ * or the annotation variable {@code @FlushMetrics(namespace = "Namespace")}. If not specified, an IllegalStateException will be thrown.
  * If both are specified then the value of the annotation variable will be used.</p>
  * 
- * <p>You can specify a custom function name with {@code @Metrics(functionName = "MyFunction")}.
+ * <p>You can specify a custom function name with {@code @FlushMetrics(functionName = "MyFunction")}.
  * If specified, this will be used instead of the function name from the Lambda context.
  * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
-public @interface Metrics {
+public @interface FlushMetrics {
     String namespace() default "";
 
     String service() default "";
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/internal/LambdaMetricsAspect.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/internal/LambdaMetricsAspect.java
@@ -27,7 +27,7 @@
 
 import software.amazon.lambda.powertools.common.internal.LambdaConstants;
 import software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor;
-import software.amazon.lambda.powertools.metrics.Metrics;
+import software.amazon.lambda.powertools.metrics.FlushMetrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
 import software.amazon.lambda.powertools.metrics.MetricsLoggerFactory;
 import software.amazon.lambda.powertools.metrics.model.DimensionSet;
@@ -39,7 +39,7 @@ public class LambdaMetricsAspect {
     private static final String SERVICE_DIMENSION = "Service";
     private static final String FUNCTION_NAME_ENV_VAR = "POWERTOOLS_METRICS_FUNCTION_NAME";
 
-    private String functionName(Metrics metrics, Context context) {
+    private String functionName(FlushMetrics metrics, Context context) {
         if (!"".equals(metrics.functionName())) {
             return metrics.functionName();
         }
@@ -52,7 +52,7 @@ private String functionName(Metrics metrics, Context context) {
         return context != null ? context.getFunctionName() : null;
     }
 
-    private String serviceNameWithFallback(Metrics metrics) {
+    private String serviceNameWithFallback(FlushMetrics metrics) {
         if (!"".equals(metrics.service())) {
             return metrics.service();
         }
@@ -61,19 +61,20 @@ private String serviceNameWithFallback(Metrics metrics) {
 
     @SuppressWarnings({ "EmptyMethod" })
     @Pointcut("@annotation(metrics)")
-    public void callAt(Metrics metrics) {
+    public void callAt(FlushMetrics metrics) {
     }
 
-    @Around(value = "callAt(metrics) && execution(@Metrics * *.*(..))", argNames = "pjp,metrics")
+    @Around(value = "callAt(metrics) && execution(@FlushMetrics * *.*(..))", argNames = "pjp,metrics")
     public Object around(ProceedingJoinPoint pjp,
-            Metrics metrics) throws Throwable {
+            FlushMetrics metrics) throws Throwable {
         Object[] proceedArgs = pjp.getArgs();
 
         if (isHandlerMethod(pjp)) {
             MetricsLogger logger = MetricsLoggerFactory.getMetricsLogger();
 
             // The MetricsLoggerFactory applies default settings from the environment or can be configured by the
-            // MetricsLoggerBuilder. We only overwrite settings if they are explicitly set in the @Metrics annotation.
+            // MetricsLoggerBuilder. We only overwrite settings if they are explicitly set in the @FlushMetrics
+            // annotation.
             if (!"".equals(metrics.namespace())) {
                 logger.setNamespace(metrics.namespace());
             }
diff --git a/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/ConfigurationPrecedenceTest.java b/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/ConfigurationPrecedenceTest.java
diff --git a/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/LambdaMetricsAspectTest.java b/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/LambdaMetricsAspectTest.java
