Feature request: Opt-in diagnostic when a metric dimension key is set again with a different value #2733

--- a/packages/metrics/src/Metrics.ts
+++ b/packages/metrics/src/Metrics.ts
@@ -239,6 +239,14 @@ class Metrics extends Utility implements MetricsInterface {
         `The number of metric dimensions must be lower than ${MAX_DIMENSION_COUNT}`
       );
     }
+    if (
+      Object.hasOwn(this.dimensions, name) ||
+      Object.hasOwn(this.defaultDimensions, name)
+    ) {
+      this.#logger.warn(
+        `Dimension "${name}" has already been added. The previous value will be overwritten.`
+      );
+    }
     this.dimensions[name] = value;
   }

diff --git a/docs/core/metrics.md b/docs/core/metrics.md
--- a/docs/core/metrics.md
+++ b/docs/core/metrics.md
@@ -119,6 +119,7 @@ Metrics has three global settings that will be used across all metrics emitted.
 | **Service**          | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME`          | `service`           |
 | **Function name**    | Function name used as dimension for the cold start metric                       | `POWERTOOLS_METRICS_FUNCTION_NAME` | `functionName`      |
 | **Disable Metrics**  | Optionally, disables all metrics flushing                                       | `POWERTOOLS_METRICS_DISABLED`      | N/A                 |
+| **Warn on dimension overwrite** | Optionally, logs a warning (once per key) when a dimension is set again with a different value | `POWERTOOLS_METRICS_WARN_ON_DIMENSION_OVERWRITE` | N/A |
 
 !!! tip "Use your application or main service as the metric namespace to easily group all metrics"
 
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
--- 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
@@ -20,6 +20,8 @@ import java.time.Instant;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.Consumer;
 
@@ -45,6 +47,10 @@ public class EmfMetricsLogger implements Metrics {
     private static final Logger LOGGER = LoggerFactory.getLogger(EmfMetricsLogger.class);
     private static final String COLD_START_METRIC = "ColdStart";
     private static final String METRICS_DISABLED_ENV_VAR = "POWERTOOLS_METRICS_DISABLED";
+    private static final String WARN_ON_DIMENSION_OVERWRITE_ENV_VAR =
+            "POWERTOOLS_METRICS_WARN_ON_DIMENSION_OVERWRITE";
+    // Dimension keys already reported as overwritten, to warn at most once per key per execution environment
+    private static final Set<String> REPORTED_OVERWRITTEN_DIMENSIONS = ConcurrentHashMap.newKeySet();
 
     private final software.amazon.cloudwatchlogs.emf.logger.MetricsLogger emfLogger;
     private final EnvironmentProvider environmentProvider;
@@ -53,6 +59,7 @@ public class EmfMetricsLogger implements Metrics {
     private Map<String, String> defaultDimensions = new HashMap<>();
     private final Map<String, Object> properties = new HashMap<>();
     private final AtomicBoolean hasMetrics = new AtomicBoolean(false);
+    private final Map<String, String> customDimensions = new HashMap<>();
 
     public EmfMetricsLogger(EnvironmentProvider environmentProvider, MetricsContext metricsContext) {
         this.emfLogger = new software.amazon.cloudwatchlogs.emf.logger.MetricsLogger(environmentProvider,
@@ -78,6 +85,8 @@ public class EmfMetricsLogger implements Metrics {
         dimensionSet.getDimensions().forEach((key, val) -> {
             try {
                 emfDimensionSet.addDimension(key, val);
+                warnIfDimensionOverwritten(key, val);
+                customDimensions.put(key, val);
             } catch (Exception e) {
                 // Ignore dimension errors
             }
@@ -107,6 +116,7 @@ public class EmfMetricsLogger implements Metrics {
                 // Ignore dimension errors
             }
         });
+        customDimensions.clear();
         emfLogger.setDimensions(emfDimensionSet);
         // Store a copy of the default dimensions
         this.defaultDimensions = new LinkedHashMap<>(dimensions);
@@ -145,6 +155,7 @@ public class EmfMetricsLogger implements Metrics {
     public void clearDefaultDimensions() {
         emfLogger.resetDimensions(false);
         defaultDimensions.clear();
+        customDimensions.clear();
     }
 
     @Override
@@ -173,6 +184,7 @@ public class EmfMetricsLogger implements Metrics {
     private void clearCustomDimensions() {
         // Reset all dimensions in the EMF logger
         emfLogger.resetDimensions(false);
+        customDimensions.clear();
 
         // Re-apply default dimensions if they exist
         if (!defaultDimensions.isEmpty()) {
@@ -188,6 +200,18 @@ public class EmfMetricsLogger implements Metrics {
         }
     }
 
+    private void warnIfDimensionOverwritten(String key, String value) {
+        if (!"true".equalsIgnoreCase(System.getenv(WARN_ON_DIMENSION_OVERWRITE_ENV_VAR))) {
+            return;
+        }
+        String previousValue = customDimensions.containsKey(key) ? customDimensions.get(key)
+                : defaultDimensions.get(key);
+        if (previousValue != null && !previousValue.equals(value) && REPORTED_OVERWRITTEN_DIMENSIONS.add(key)) {
+            LOGGER.warn("Dimension \"{}\" has already been added. The previous value (\"{}\") will be overwritten "
+                    + "with \"{}\".", key, previousValue, value);
+        }
+    }
+
     @Override
     public void captureColdStartMetric(Context context,
             software.amazon.lambda.powertools.metrics.model.DimensionSet dimensions) {