From 198863f5832050d1f185aa298718a03eecd6c8ce Mon Sep 17 00:00:00 2001 From: hidingmyname <140602238+hidingmyname@users.noreply.github.com> Date: Wed, 18 Nov 2026 04:29:33 +0800 Subject: [PATCH] fix(metrics): clarify empty application metrics warning The cold-start metric is published through a separate logger, so the empty check only describes application metrics. Clarify the warning without changing publication or raise-on-empty behavior, document the distinction, and preserve the empty/cold-start exception invariants through the public Metrics interface. --- docs/core/metrics.md | 10 ++++--- .../metrics/internal/EmfMetricsLogger.java | 2 +- .../internal/EmfMetricsLoggerTest.java | 30 ++++++++++--------- 3 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 372fcc7e1..39527c022 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -303,9 +303,11 @@ You can add dimensions to your metrics using the `addDimension` method. You can ### Flushing metrics -The `@FlushMetrics` annotation **validates**, **serializes**, and **flushes** all your metrics. During metrics validation, -if no metrics are provided no exception will be raised. If metrics are provided, and any of the following criteria are -not met, `IllegalStateException` or `IllegalArgumentException` exceptions will be raised. +The `@FlushMetrics` annotation **validates**, **serializes**, and **flushes** all your application metrics. +When no application metrics are provided, it logs a warning instead of publishing an empty EMF document. +The `ColdStart` metric may still be published separately when enabled. +If metrics are provided, and any of the following criteria are not met, `IllegalStateException` or +`IllegalArgumentException` exceptions will be raised. !!! tip "Metric validation" @@ -314,7 +316,7 @@ not met, `IllegalStateException` or `IllegalArgumentException` exceptions will b - Metric values must be valid numbers -If you want to ensure that at least one metric is emitted, you can pass `raiseOnEmptyMetrics = true` to the `@FlushMetrics` annotation: +If you want to ensure that at least one application metric is emitted, you can pass `raiseOnEmptyMetrics = true` to the `@FlushMetrics` annotation. The separately published `ColdStart` metric does not satisfy this check: === "MetricsRaiseOnEmpty.java" 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 index 611d4dcc6..7f66a8cdb 100644 --- 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 @@ -160,7 +160,7 @@ public void flush() { if (raiseOnEmptyMetrics.get()) { throw new IllegalStateException("No metrics were emitted"); } else { - LOGGER.warn("No metrics were emitted"); + LOGGER.warn("No application metrics to publish. The cold-start metric may be published if enabled."); } } else { emfLogger.flush(); diff --git a/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLoggerTest.java b/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLoggerTest.java index 5e597e835..d37744210 100644 --- a/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLoggerTest.java +++ b/powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/internal/EmfMetricsLoggerTest.java @@ -18,11 +18,8 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy; import java.io.ByteArrayOutputStream; -import java.io.File; import java.io.PrintStream; import java.lang.reflect.Method; -import java.nio.charset.StandardCharsets; -import java.nio.file.Files; import java.time.Instant; import java.util.stream.Stream; @@ -391,22 +388,27 @@ void shouldRaiseExceptionOnEmptyMetrics() { } @Test - void shouldLogWarningOnEmptyMetrics() throws Exception { - // Given - File logFile = new File("target/metrics-test.log"); - - // When - // Flushing without adding metrics + void shouldNotPublishEmptyApplicationMetrics() { metrics.flush(); - // Then - // Read the log file and check for the warning - String logContent = Files.readString(logFile.toPath(), StandardCharsets.UTF_8); - assertThat(logContent).contains("No metrics were emitted"); - // No EMF output should be generated assertThat(outputStreamCaptor.toString().trim()).isEmpty(); } + @Test + void shouldRejectEmptyApplicationMetricsAfterPublishingColdStart() throws Exception { + metrics.setRaiseOnEmptyMetrics(true); + metrics.captureColdStartMetric(); + + String coldStartOutput = outputStreamCaptor.toString().trim(); + JsonNode coldStartMetric = objectMapper.readTree(coldStartOutput); + assertThat(coldStartMetric.get("ColdStart").asDouble()).isEqualTo(1.0); + + assertThatThrownBy(metrics::flush) + .isInstanceOf(IllegalStateException.class) + .hasMessage("No metrics were emitted"); + assertThat(outputStreamCaptor.toString().trim()).isEqualTo(coldStartOutput); + } + @Test void shouldClearDefaultDimensions() throws Exception { // Given