Feature request: Clarify the "No metrics were emitted" warning when the ColdStart metric was published #2731

Use case

A handler annotated with @FlushMetrics(captureColdStart = true) that adds no application metrics on a given invocation (e.g. a cold start that takes an early-return path) logs:

WARN software.amazon.lambda.powertools.metrics.internal.EmfMetricsLogger - No metrics were emitted

while the same invocation does publish the ColdStart metric. When reading the logs (or alerting on Powertools warnings) this reads as if nothing was published, which is not the case.

Location (aws-powertools/powertools-lambda-java @ default branch 6455f45):

• EmfMetricsLogger.java:159-164 — flush warns No metrics were emitted when the application metrics collection is empty.
• EmfMetricsLogger.java:215-216 — the cold-start metric is flushed through its own logger instance.

Current code:

        if (!hasMetrics.get()) {
            if (raiseOnEmptyMetrics.get()) {
                throw new IllegalStateException("No metrics were emitted");
            } else {
                LOGGER.warn("No metrics were emitted");
            }
        }

Problem: The cold-start metric does not count towards the empty check, so the warning fires even though a ColdStart EMF document was published in the same invocation. The warning's condition is correct; only the wording overstates it.

@FlushMetrics(captureColdStart = true, namespace = "MyNamespace")
public String handleRequest(Map<String, Object> input, Context context) {
    return "OK";   // no application metrics
}
// cold start: EMF line with "ColdStart": 1.0 is printed, and the WARN above is logged

Reproduction: observed with a unit test (captureColdStartMetric() then flush(), both on main at d767ff5): stdout contained the ColdStart EMF document and the log contained No metrics were emitted. Current main (6455f45) differs only by docs dependency bumps and a powertools-batch MultiThreadMDC change, so the code paths above are unchanged.

Solution/User Experience

Already fixed in aws-powertools/powertools-lambda-python

PR: aws-powertools/powertools-lambda-python#1935 — "fix(metrics): clarify no-metrics user warning" (merged 2023-02-16T13:49:10Z, merge commit 183f23310b9).

The Python runtime had the same misleading message in the same situation and reworded it to say that no application metrics were published and that the cold-start metric may still be published (current wording: cloudwatch.py#L474).

How powertools-lambda-python fixed it:

--- a/aws_lambda_powertools/metrics/base.py
+++ b/aws_lambda_powertools/metrics/base.py
@@ -391,7 +391,11 @@ def decorate(event, context):
                     self._add_cold_start_metric(context=context)
             finally:
                 if not raise_on_empty_metrics and not self.metric_set:
-                    warnings.warn("No metrics to publish, skipping", stacklevel=2)
+                    warnings.warn(
+                        "No application metrics to publish. The cold-start metric may be published if enabled. "
+                        "If application metrics should never be empty, consider using 'raise_on_empty_metrics'",
+                        stacklevel=2,
+                    )
                 else:
                     metrics = self.serialize_metric_set()
                     self.clear_metrics()

Suggested fix

Reword the empty-metrics warning in EmfMetricsLogger.flush following the Python wording, so it is accurate when only the cold-start metric was published; it is still logged whenever no application metrics were added, and the raiseOnEmptyMetrics exception message stays unchanged:

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
@@ -160,7 +160,7 @@ public class EmfMetricsLogger implements Metrics {
             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();

Verified on d767ff5 (OpenJDK 25.0.5, Maven 3.9.16): a new ColdStartWarningMessageTest (calls captureColdStartMetric() then flush() and checks the logged warning) fails without this patch and passes with it; apart from EmfMetricsLoggerTest.shouldLogWarningOnEmptyMetrics, whose assertion on the old wording was updated accordingly, no other test results change.

I can submit a PR for this.

Alternative solutions

- Suppress the warning when only ColdStart was emitted: hides a legitimate "no application metrics" signal; not proposed.
- Leave as is: users have to know that ColdStart is flushed separately to interpret the warning correctly.

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Java) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, TypeScript, and .NET

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Java) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, TypeScript, and .NET

Related issues checked

Checked: #1890 (don't flush an empty EMF root when there are no metrics) concerns the empty-flush output, not this wording; #2328, #297 and #2440 are unrelated.