feat(metrics): add EphemeralMetrics as a non-singleton option

[heitorlessa]

Issue number: #1668

Summary

By default, Metrics shares data across instances. This allows customers to instantiate Metrics in multiple places throughout their code - be a separate file, a middleware, or an abstraction.

However, there are three cases where this is a disadvantage:

• You want to create the same metrics for different applications
• You use a metric dimension to distinguish a metric per tenant (EMF mandates the same dimension for all metrics in a given JSON blob).

Changes

Please provide a summary of what's being changed

This PR introduces a new class: EphemeralMetrics. This makes an explicit contract that instances of EphemeralMetrics will not share data sets (metrics, dimensions, metadata).

Quick summary on differences:

Feature	Metrics	EphemeralMetrics
Share data across instances (metrics, dimensions, metadata, etc.)	Yes	-
Set default dimensions to persist across Lambda invocations (metric flush)	Yes	-

User experience

Please share what the user experience looks like before and after this change

from aws_lambda_powertools.metrics import EphemeralMetrics
from aws_lambda_powertools.metrics import MetricUnit
from aws_lambda_powertools.utilities.typing import LambdaContext

metrics = EphemeralMetrics()

@metrics.log_metrics
def lambda_handler(event: dict, context: LambdaContext):
    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics
• Explicit test for nested log_metrics use case

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[heitorlessa]

Still looking for a class name to avoid this implementation.

• EphemeralMetrics
• TransientMetrics
• NonDurableMetrics
• MetricManager

[heitorlessa]

Docs with a new section named Metrics isolation and explanation about the constraints that led us to our Metrics design (and why a new class name).

[heitorlessa]

both Leandro and Ruben are PTO, therefore I'm merging after my best due diligence in review, docs, and tests.