Add support for POWERTOOLS_METRICS_DISABLED environment variable.

Author: phipag

docs/core/metrics.md

@@ -109,15 +109,18 @@ Visit the AWS documentation for a complete explanation for [Amazon CloudWatch co
 
 ## Getting started
 
-Metrics has two global settings that will be used across all metrics emitted. Use your application or main service as the metric namespace to easily group all metrics:
+Metrics has three global settings that will be used across all metrics emitted. Use your application or main service as the metric namespace to easily group all metrics:
 
-| Setting              | Description                                                                     | Environment variable           | Decorator parameter |
-| -------------------- | ------------------------------------------------------------------------------- | ------------------------------ | ------------------- |
-| **Metric namespace** | Logical container where all metrics will be placed e.g. `ServerlessAirline`     | `POWERTOOLS_METRICS_NAMESPACE` | `namespace`         |
-| **Service**          | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME`      | `service`           |
+| Setting                        | Description                                                                     | Environment variable           | Decorator parameter |
+| ------------------------------ | ------------------------------------------------------------------------------- | ------------------------------ | ------------------- |
+| **Metric namespace**           | Logical container where all metrics will be placed e.g. `ServerlessAirline`     | `POWERTOOLS_METRICS_NAMESPACE` | `namespace`         |
+| **Service**                    | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME`      | `service`           |
+| **Disable Powertools Metrics** | Optionally, disables all Powertools metrics                                     | `POWERTOOLS_METRICS_DISABLED`  | N/A                 |
 
 !!! tip "Use your application or main service as the metric namespace to easily group all metrics"
 
+!!! info "`POWERTOOLS_METRICS_DISABLED` will not disable default metrics created by AWS services."
+
 ### Order of Precedence of `MetricsLogger` configuration
 
 The `MetricsLogger` Singleton can be configured by three different interfaces. The following order of precedence applies:

docs/index.md

@@ -239,9 +239,9 @@ Use the following [dependency matrix](https://github.com/eclipse-aspectj/aspectj
 |----------------------------------------|----------------------------------------------------------------------------------------|---------------------------|
 | **POWERTOOLS_SERVICE_NAME**            | Sets service name used for tracing namespace, metrics dimension and structured logging | All                       |
 | **POWERTOOLS_METRICS_NAMESPACE**       | Sets namespace used for metrics                                                        | [Metrics](./core/metrics) |
+| **POWERTOOLS_METRICS_DISABLED**       | Disables all flushing of metrics                                                        | [Metrics](./core/metrics) |
 | **POWERTOOLS_LOGGER_SAMPLE_RATE**      | Debug log sampling                                                                     | [Logging](./core/logging) |
 | **POWERTOOLS_LOG_LEVEL**               | Sets logging level                                                                     | [Logging](./core/logging) |
 | **POWERTOOLS_LOGGER_LOG_EVENT**        | Enables/Disables whether to log the incoming event when using the aspect               | [Logging](./core/logging) |
 | **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Enables/Disables tracing mode to capture method response                               | [Tracing](./core/tracing) |
 | **POWERTOOLS_TRACER_CAPTURE_ERROR**    | Enables/Disables tracing mode to capture method error                                  | [Tracing](./core/tracing) |
-

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

@@ -45,6 +45,7 @@ public class EmfMetricsLogger implements MetricsLogger {
     private static final String TRACE_ID_PROPERTY = "xray_trace_id";
     private static final String REQUEST_ID_PROPERTY = "function_request_id";
     private static final String COLD_START_METRIC = "ColdStart";
+    private static final String METRICS_DISABLED_ENV_VAR = "POWERTOOLS_METRICS_DISABLED";
 
     private final software.amazon.cloudwatchlogs.emf.logger.MetricsLogger emfLogger;
     private final EnvironmentProvider environmentProvider;
@@ -142,6 +143,11 @@ public void clearDefaultDimensions() {
 
     @Override
     public void flush() {
+        if (isMetricsDisabled()) {
+            LOGGER.debug("Metrics are disabled, skipping flush");
+            return;
+        }
+
         Validator.validateNamespace(namespace);
 
         if (!hasMetrics.get()) {
@@ -158,6 +164,11 @@ public void flush() {
     public void captureColdStartMetric(Context context,
             software.amazon.lambda.powertools.metrics.model.DimensionSet dimensions) {
         if (isColdStart()) {
+            if (isMetricsDisabled()) {
+                LOGGER.debug("Metrics are disabled, skipping cold start metric capture");
+                return;
+            }
+
             Validator.validateNamespace(namespace);
 
             software.amazon.cloudwatchlogs.emf.logger.MetricsLogger coldStartLogger = new software.amazon.cloudwatchlogs.emf.logger.MetricsLogger();
@@ -203,6 +214,11 @@ public void captureColdStartMetric(software.amazon.lambda.powertools.metrics.mod
     @Override
     public void flushSingleMetric(String name, double value, MetricUnit unit, String namespace,
             software.amazon.lambda.powertools.metrics.model.DimensionSet dimensions) {
+        if (isMetricsDisabled()) {
+            LOGGER.debug("Metrics are disabled, skipping single metric flush");
+            return;
+        }
+
         Validator.validateNamespace(namespace);
 
         // Create a new logger for this single metric
@@ -235,6 +251,11 @@ public void flushSingleMetric(String name, double value, MetricUnit unit, String
         singleMetricLogger.flush();
     }
 
+    private boolean isMetricsDisabled() {
+        String disabledValue = System.getenv(METRICS_DISABLED_ENV_VAR);
+        return "true".equalsIgnoreCase(disabledValue);
+    }
+
     private Unit convertUnit(MetricUnit unit) {
         switch (unit) {
             case SECONDS:

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

@@ -31,6 +31,7 @@
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
+import org.junitpioneer.jupiter.SetEnvironmentVariable;
 
 import com.amazonaws.services.lambda.runtime.Context;
 import com.fasterxml.jackson.databind.JsonNode;
@@ -458,4 +459,43 @@ void shouldFlushSingleMetricWithoutDimensions() throws Exception {
                 .isEqualTo("SingleNamespace");
     }
 
+    @Test
+    @SetEnvironmentVariable(key = "POWERTOOLS_METRICS_DISABLED", value = "true")
+    void shouldNotFlushMetricsWhenDisabled() {
+        // When
+        metricsLogger.addMetric("test-metric", 100, MetricUnit.COUNT);
+        metricsLogger.flush();
+
+        // Then
+        String emfOutput = outputStreamCaptor.toString().trim();
+        assertThat(emfOutput).isEmpty();
+    }
+
+    @Test
+    @SetEnvironmentVariable(key = "POWERTOOLS_METRICS_DISABLED", value = "true")
+    void shouldNotCaptureColdStartMetricWhenDisabled() {
+        // Given
+        Context testContext = new TestContext();
+
+        // When
+        metricsLogger.captureColdStartMetric(testContext);
+
+        // Then
+        String emfOutput = outputStreamCaptor.toString().trim();
+        assertThat(emfOutput).isEmpty();
+    }
+
+    @Test
+    @SetEnvironmentVariable(key = "POWERTOOLS_METRICS_DISABLED", value = "true")
+    void shouldNotFlushSingleMetricWhenDisabled() {
+        // Given
+        DimensionSet dimensions = DimensionSet.of("CustomDim", "CustomValue");
+
+        // When
+        metricsLogger.flushSingleMetric("single-metric", 200, MetricUnit.COUNT, "SingleNamespace", dimensions);
+
+        // Then
+        String emfOutput = outputStreamCaptor.toString().trim();
+        assertThat(emfOutput).isEmpty();
+    }
 }