Update default dimension and namespace logic to have the precedence: @metrics annotation. MetricsLoggerBuilder, Environment variables.

phipag · phipag · commit 424976682b90 · 2025-06-03T13:32:06.000+02:00
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/Metrics.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/Metrics.java
@@ -20,13 +20,12 @@
 import java.lang.annotation.Target;
 
 /**
- * {@code Metrics} is used to signal that the annotated method should be
- * extended with Metrics functionality.
+ * {@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.
  *
  * <p>{@code Metrics} 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 of the MetricsLogger class,
- * to simplify the user experience when used with AWS Lambda.
+ * {@code Metrics} manages the life-cycle and configuration of the MetricsLogger to simplify the user experience when used with AWS Lambda.
  *
  * <p>{@code Metrics} should be used with the handleRequest method of a class
  * which implements either
@@ -64,10 +63,10 @@
     String namespace() default "";
 
     String service() default "";
-    
+
     String functionName() default "";
 
     boolean captureColdStart() default false;
 
     boolean raiseOnEmptyMetrics() default false;
-}
+}
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsLoggerBuilder.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsLoggerBuilder.java
@@ -64,7 +64,8 @@ public MetricsLoggerBuilder withNamespace(String namespace) {
     }
 
     /**
-     * Set the service name
+     * Set the service name. Does not apply if used in combination with default dimensions. If you would like to use a
+     * service name with default dimensions, use {@link #withDefaultDimension(String, String)} instead.
      *
      * @param service the service name
      * @return this builder
@@ -86,7 +87,7 @@ public MetricsLoggerBuilder withRaiseOnEmptyMetrics(boolean raiseOnEmptyMetrics)
     }
 
     /**
-     * Add a default dimension
+     * Add a default dimension.
      *
      * @param key   the dimension key
      * @param value the dimension value
@@ -126,13 +127,13 @@ public MetricsLogger build() {
 
         metricsLogger.setRaiseOnEmptyMetrics(raiseOnEmptyMetrics);
 
-        if (!defaultDimensions.isEmpty()) {
-            metricsLogger.setDefaultDimensions(defaultDimensions);
+        if (service != null) {
+            metricsLogger.setDefaultDimensions(Map.of("Service", service));
         }
 
-        // Add Service dimension separately to ensure it's not mixed with other default dimensions
-        if (service != null) {
-            metricsLogger.addDimension("Service", service);
+        // If the user provided default dimension, we overwrite the default Service dimension again
+        if (!defaultDimensions.isEmpty()) {
+            metricsLogger.setDefaultDimensions(defaultDimensions);
         }
 
         return metricsLogger;
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsLoggerFactory.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsLoggerFactory.java
@@ -14,12 +14,12 @@
 
 package software.amazon.lambda.powertools.metrics;
 
+import java.util.Map;
+
+import software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor;
 import software.amazon.lambda.powertools.metrics.provider.EmfMetricsProvider;
 import software.amazon.lambda.powertools.metrics.provider.MetricsProvider;
 
-import java.util.HashMap;
-import java.util.Map;
-
 /**
  * Factory for accessing the singleton MetricsLogger instance
  */
@@ -38,28 +38,19 @@ private MetricsLoggerFactory() {
     public static synchronized MetricsLogger getMetricsLogger() {
         if (metricsLogger == null) {
             metricsLogger = provider.getMetricsLogger();
-            
+
             // Apply default configuration from environment variables
             String envNamespace = System.getenv("POWERTOOLS_METRICS_NAMESPACE");
             if (envNamespace != null) {
                 metricsLogger.setNamespace(envNamespace);
             }
-            
-            String envService = System.getenv("POWERTOOLS_SERVICE_NAME");
-            if (envService != null) {
-                Map<String, String> dimensions = new HashMap<>();
-                dimensions.put("Service", envService);
-                metricsLogger.setDefaultDimensions(dimensions);
-            } else {
-                Map<String, String> dimensions = new HashMap<>();
-                dimensions.put("Service", "service_undefined");
-                metricsLogger.setDefaultDimensions(dimensions);
-            }
+
+            metricsLogger.setDefaultDimensions(Map.of("Service", LambdaHandlerProcessor.serviceName()));
         }
-        
+
         return metricsLogger;
     }
-    
+
     /**
      * Set the metrics provider
      *
@@ -73,4 +64,4 @@ public static synchronized void setMetricsProvider(MetricsProvider metricsProvid
         // Reset the logger so it will be recreated with the new provider
         metricsLogger = null;
     }
-}
+}
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLogger.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLogger.java
@@ -93,7 +93,7 @@ public void setDefaultDimensions(Map<String, String> defaultDimensions) {
         // Store a copy of the default dimensions
         this.defaultDimensions = new HashMap<>(defaultDimensions);
     }
-    
+
     @Override
     public software.amazon.lambda.powertools.metrics.model.DimensionSet getDefaultDimensions() {
         return software.amazon.lambda.powertools.metrics.model.DimensionSet.of(defaultDimensions);
@@ -268,4 +268,4 @@ private Unit convertUnit(MetricUnit unit) {
                 return Unit.NONE;
         }
     }
-}
+}
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
@@ -17,13 +17,16 @@
 import static software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor.coldStartDone;
 import static software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor.extractContext;
 import static software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor.isHandlerMethod;
-import static software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor.serviceName;
 
-import com.amazonaws.services.lambda.runtime.Context;
+import java.util.Map;
+
 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.annotation.Around;
 import org.aspectj.lang.annotation.Aspect;
 import org.aspectj.lang.annotation.Pointcut;
+
+import com.amazonaws.services.lambda.runtime.Context;
+
 import software.amazon.lambda.powertools.common.internal.LambdaHandlerProcessor;
 import software.amazon.lambda.powertools.metrics.Metrics;
 import software.amazon.lambda.powertools.metrics.MetricsLogger;
@@ -34,46 +37,49 @@
 public class LambdaMetricsAspect {
     public static final String TRACE_ID_PROPERTY = "xray_trace_id";
     public static final String REQUEST_ID_PROPERTY = "function_request_id";
-    private static final String NAMESPACE = System.getenv("POWERTOOLS_METRICS_NAMESPACE");
 
-    private static String service(Metrics metrics) {
-        return !"".equals(metrics.service()) ? metrics.service() : serviceName();
-    }
-    
-    private String namespace(Metrics metrics) {
-        return !"".equals(metrics.namespace()) ? metrics.namespace() : NAMESPACE;
-    }
-    
     private String functionName(Metrics metrics, Context context) {
         if (!"".equals(metrics.functionName())) {
             return metrics.functionName();
         }
         return context != null ? context.getFunctionName() : null;
     }
 
-    @SuppressWarnings({"EmptyMethod"})
+    private String serviceNameWithFallback(Metrics metrics) {
+        if (!"".equals(metrics.service())) {
+            return metrics.service();
+        }
+        return LambdaHandlerProcessor.serviceName();
+    }
+
+    @SuppressWarnings({ "EmptyMethod" })
     @Pointcut("@annotation(metrics)")
     public void callAt(Metrics metrics) {
     }
 
     @Around(value = "callAt(metrics) && execution(@Metrics * *.*(..))", argNames = "pjp,metrics")
     public Object around(ProceedingJoinPoint pjp,
-                         Metrics metrics) throws Throwable {
+            Metrics metrics) throws Throwable {
         Object[] proceedArgs = pjp.getArgs();
 
         if (isHandlerMethod(pjp)) {
             MetricsLogger logger = MetricsLoggerFactory.getMetricsLogger();
 
-            // Add service dimension separately
-            logger.addDimension("Service", service(metrics));
+            // 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.
+            if (!"".equals(metrics.namespace())) {
+                logger.setNamespace(metrics.namespace());
+            }
 
-            // Set namespace
-            String metricsNamespace = namespace(metrics);
-            if (metricsNamespace != null) {
-                logger.setNamespace(metricsNamespace);
+            // If the default dimensions are larger than 1 or do not contain the "Service" dimension, it means that the
+            // user overwrote them manually e.g. using MetricsLoggerBuilder. In this case, we don't set the service
+            // default dimension.
+            if (!"".equals(metrics.service())
+                    && logger.getDefaultDimensions().getDimensionKeys().size() <= 1
+                    && logger.getDefaultDimensions().getDimensionKeys().contains("Service")) {
+                logger.setDefaultDimensions(Map.of("Service", metrics.service()));
             }
 
-            // Configure other settings
             logger.setRaiseOnEmptyMetrics(metrics.raiseOnEmptyMetrics());
 
             // Add trace ID metadata if available
@@ -84,18 +90,19 @@ public Object around(ProceedingJoinPoint pjp,
 
             if (null != extractedContext) {
                 logger.addMetadata(REQUEST_ID_PROPERTY, extractedContext.getAwsRequestId());
-                
+
                 // Only capture cold start metrics if configured
                 if (metrics.captureColdStart()) {
                     // Get function name from annotation or context
                     String funcName = functionName(metrics, extractedContext);
-                    
+
                     // Create dimensions with service and function name
                     DimensionSet coldStartDimensions = DimensionSet.of(
-                        "Service", service(metrics),
-                        "FunctionName", funcName != null ? funcName : extractedContext.getFunctionName()
-                    );
-                    
+                            "Service",
+                            logger.getDefaultDimensions().getDimensions().getOrDefault("Service",
+                                    serviceNameWithFallback(metrics)),
+                            "FunctionName", funcName != null ? funcName : extractedContext.getFunctionName());
+
                     logger.captureColdStartMetric(extractedContext, coldStartDimensions);
                 }
             }
@@ -110,4 +117,4 @@ public Object around(ProceedingJoinPoint pjp,
 
         return pjp.proceed(proceedArgs);
     }
-}
+}
diff --git a/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/provider/MetricsProvider.java b/powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/provider/MetricsProvider.java
@@ -20,11 +20,11 @@
  * Interface for metrics provider implementations
  */
 public interface MetricsProvider {
-    
+
     /**
      * Get a new instance of a metrics logger
      *
      * @return a new metrics logger instance
      */
     MetricsLogger getMetricsLogger();
-}
+}

Original file line number	Diff line number	Diff line change
`@@ -64,7 +64,8 @@ public MetricsLoggerBuilder withNamespace(String namespace) {`
`64`	`64`	`}`
`65`	`65`
`66`	`66`	`/**`
`67`		`- * Set the service name`
	`67`	`+ * Set the service name. Does not apply if used in combination with default dimensions. If you would like to use a`
	`68`	`+ * service name with default dimensions, use {@link #withDefaultDimension(String, String)} instead.`
`68`	`69`	`*`
`69`	`70`	`* @param service the service name`
`70`	`71`	`* @return this builder`
`@@ -86,7 +87,7 @@ public MetricsLoggerBuilder withRaiseOnEmptyMetrics(boolean raiseOnEmptyMetrics)`
`86`	`87`	`}`
`87`	`88`
`88`	`89`	`/**`
`89`		`- * Add a default dimension`
	`90`	`+ * Add a default dimension.`
`90`	`91`	`*`
`91`	`92`	`* @param key the dimension key`
`92`	`93`	`* @param value the dimension value`
`@@ -126,13 +127,13 @@ public MetricsLogger build() {`
`126`	`127`
`127`	`128`	`metricsLogger.setRaiseOnEmptyMetrics(raiseOnEmptyMetrics);`
`128`	`129`
`129`		`- if (!defaultDimensions.isEmpty()) {`
`130`		`- metricsLogger.setDefaultDimensions(defaultDimensions);`
	`130`	`+ if (service != null) {`
	`131`	`+ metricsLogger.setDefaultDimensions(Map.of("Service", service));`
`131`	`132`	`}`
`132`	`133`
`133`		`- // Add Service dimension separately to ensure it's not mixed with other default dimensions`
`134`		`- if (service != null) {`
`135`		`- metricsLogger.addDimension("Service", service);`
	`134`	`+ // If the user provided default dimension, we overwrite the default Service dimension again`
	`135`	`+ if (!defaultDimensions.isEmpty()) {`
	`136`	`+ metricsLogger.setDefaultDimensions(defaultDimensions);`
`136`	`137`	`}`
`137`	`138`
`138`	`139`	`return metricsLogger;`
Original file line number	Diff line number	Diff line change
`@@ -93,7 +93,7 @@ public void setDefaultDimensions(Map<String, String> defaultDimensions) {`
`93`	`93`	`// Store a copy of the default dimensions`
`94`	`94`	`this.defaultDimensions = new HashMap<>(defaultDimensions);`
`95`	`95`	`}`
`96`		`-`
	`96`	`+`
`97`	`97`	`@Override`
`98`	`98`	`public software.amazon.lambda.powertools.metrics.model.DimensionSet getDefaultDimensions() {`
`99`	`99`	`return software.amazon.lambda.powertools.metrics.model.DimensionSet.of(defaultDimensions);`
`@@ -268,4 +268,4 @@ private Unit convertUnit(MetricUnit unit) {`
`268`	`268`	`return Unit.NONE;`
`269`	`269`	`}`
`270`	`270`	`}`
`271`		`-}`
	`271`	`+}`