diff --git a/.agents/skills/building-lambda-functions-with-powertools-python/references/metrics.md b/.agents/skills/building-lambda-functions-with-powertools-python/references/metrics.md index 530014b21ff..b06f2e50619 100644 --- a/.agents/skills/building-lambda-functions-with-powertools-python/references/metrics.md +++ b/.agents/skills/building-lambda-functions-with-powertools-python/references/metrics.md @@ -133,6 +133,10 @@ def lambda_handler(event: dict, context: LambdaContext): CloudWatch EMF supports a max of 100 metrics per batch. Metrics utility will flush all metrics when adding the 100th metric. Subsequent metrics (101th+) will be aggregated into a new EMF object, for your convenience. +> **Note: Note: Non-finite values** + +CloudWatch EMF only accepts finite numbers. `add_metric` skips a `NaN` or infinite value and emits a `PowertoolsUserWarning`, so the other metrics in the batch are still published. + > **Warning: Warning: Do not create metrics or dimensions outside the handler** Metrics or dimensions added in the global scope will only be added during cold start. Disregard if that's the intended behavior. diff --git a/aws_lambda_powertools/metrics/base.py b/aws_lambda_powertools/metrics/base.py index 05c1fcbdfe9..1fb2d6552b8 100644 --- a/aws_lambda_powertools/metrics/base.py +++ b/aws_lambda_powertools/metrics/base.py @@ -10,6 +10,7 @@ import functools import json import logging +import math import numbers import os import warnings @@ -38,6 +39,7 @@ ) from aws_lambda_powertools.shared import constants from aws_lambda_powertools.shared.functions import is_durable_context, resolve_env_var_choice +from aws_lambda_powertools.warnings import PowertoolsUserWarning if TYPE_CHECKING: from collections.abc import Callable, Generator @@ -152,6 +154,14 @@ def add_metric( unit = self._extract_metric_unit_value(unit=unit) resolution = self._extract_metric_resolution_value(resolution=resolution) + if not math.isfinite(value): + warnings.warn( + f"The metric {name} has a non-finite value ({value}) and won't be added. " + "CloudWatch EMF only accepts finite numbers.", + category=PowertoolsUserWarning, + stacklevel=2, + ) + return metric: dict = self.metric_set.get(name, defaultdict(list)) metric["Unit"] = unit metric["StorageResolution"] = resolution @@ -657,6 +667,9 @@ def single_metric( metric.add_dimension(name=dim_name, value=dim_value) yield metric - metric_set = metric.serialize_metric_set() + # add_metric drops a non-finite value with a warning, leaving nothing to publish + if metric.metric_set: + metric_set = metric.serialize_metric_set() finally: - print(json.dumps(metric_set, separators=(",", ":"))) + if metric_set is not None: + print(json.dumps(metric_set, separators=(",", ":"))) diff --git a/aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py b/aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py index f8675018a24..e31b13089b5 100644 --- a/aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py +++ b/aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py @@ -3,6 +3,7 @@ import datetime as dt import json import logging +import math import numbers import os import warnings @@ -165,6 +166,14 @@ def add_metric( metric_resolutions=self._metric_resolutions, resolution=resolution, ) + if not math.isfinite(value): + warnings.warn( + f"The metric {name} has a non-finite value ({value}) and won't be added. " + "CloudWatch EMF only accepts finite numbers.", + category=PowertoolsUserWarning, + stacklevel=2, + ) + return metric: dict = self.metric_set.get(name, defaultdict(list)) metric["Unit"] = unit metric["StorageResolution"] = resolution diff --git a/docs/core/metrics/index.md b/docs/core/metrics/index.md index 4bfbea99b6a..8a84362bda1 100644 --- a/docs/core/metrics/index.md +++ b/docs/core/metrics/index.md @@ -81,6 +81,9 @@ You can create metrics using `add_metric`, and you can create dimensions for all ???+ note "Note: Metrics overflow" CloudWatch EMF supports a max of 100 metrics per batch. Metrics utility will flush all metrics when adding the 100th metric. Subsequent metrics (101th+) will be aggregated into a new EMF object, for your convenience. +???+ note "Note: Non-finite values" + CloudWatch EMF only accepts finite numbers. `add_metric` skips a `NaN` or infinite value and emits a `PowertoolsUserWarning`, so the other metrics in the batch are still published. + ???+ warning "Warning: Do not create metrics or dimensions outside the handler" Metrics or dimensions added in the global scope will only be added during cold start. Disregard if that's the intended behavior. diff --git a/tests/functional/metrics/required_dependencies/test_metrics_cloudwatch_emf.py b/tests/functional/metrics/required_dependencies/test_metrics_cloudwatch_emf.py index 9d6c2cc8ee5..ed4363f66a6 100644 --- a/tests/functional/metrics/required_dependencies/test_metrics_cloudwatch_emf.py +++ b/tests/functional/metrics/required_dependencies/test_metrics_cloudwatch_emf.py @@ -29,6 +29,7 @@ MIN_METRIC_NAME_LENGTH, ) from aws_lambda_powertools.metrics.provider.cloudwatch_emf.exceptions import MetricNameError +from aws_lambda_powertools.warnings import PowertoolsUserWarning if TYPE_CHECKING: from aws_lambda_powertools.metrics.provider.cloudwatch_emf.types import ( @@ -1251,6 +1252,50 @@ def test_add_dimensions_with_empty_value(namespace, capsys, metric): assert my_dimension not in output +def _reject_non_finite(constant: str): + raise ValueError(f"EMF output contains {constant}, which is not valid JSON") + + +@pytest.mark.parametrize("value", [float("nan"), float("inf"), float("-inf")]) +def test_add_metric_with_non_finite_value(namespace, capsys, metric, dimension, value): + # GIVEN Metrics is initialized + my_metrics = Metrics(namespace=namespace) + my_metrics.add_dimension(**dimension) + + # WHEN we add a non-finite metric value next to a valid metric + with pytest.warns(PowertoolsUserWarning, match="The metric bad_metric has a non-finite value *"): + my_metrics.add_metric(name="bad_metric", unit=MetricUnit.Count, value=value) + my_metrics.add_metric(**metric) + my_metrics.flush_metrics() + + # THEN the EMF output is valid JSON and only contains the valid metric + output = json.loads(capsys.readouterr().out.strip(), parse_constant=_reject_non_finite) + assert "bad_metric" not in output + assert output[metric["name"]] == [1.0] + + +def test_single_metric_with_non_finite_value(namespace, capsys): + # GIVEN a single metric with a NaN value + # WHEN the context manager exits + with pytest.warns(PowertoolsUserWarning, match="The metric bad_metric has a non-finite value *"): + with single_metric(name="bad_metric", unit=MetricUnit.Count, value=float("nan"), namespace=namespace): + pass + + # THEN nothing is published and no exception is raised + assert capsys.readouterr().out == "" + + +def test_single_metric_body_raises(namespace, capsys): + # GIVEN a single metric whose context manager body raises + # WHEN the exception leaves the context manager + with pytest.raises(RuntimeError, match="boom"): + with single_metric(name="my_metric", unit=MetricUnit.Count, value=1, namespace=namespace): + raise RuntimeError("boom") + + # THEN no metric or `null` line is printed + assert capsys.readouterr().out == "" + + def test_get_and_set_namespace_and_service_properties(namespace, service, metrics, capsys): # GIVEN Metrics instance is initialized without namespace and service my_metrics = Metrics()