improv(metrics): Add thread-safety to Metrics utility through thread-local Metrics instance management

[phipag]

Summary

This PR makes the Metrics utility thread-safe for scenarios when used as a singleton in a Lambda handler that uses multi-threading while modifying dimensions or other metadata from within threads.

Changes

The main change is the introduction of a RequestScopedMetricsProxy. This class lazily initializes the corresponding metrics backend on the first invocation of e.g. .addMetric(...) using a ConcurrentHashMap<String, Metrics> keyed by X-Ray trace ID. This ensures that concurrent usages of Metrics are isolated per Lambda invocation (not per thread), and metrics added in child threads are correctly flushed.

This is the same approach we use in log buffering. See for example:

powertools-lambda-java/powertools-logging/powertools-logging-log4j/src/main/java/software/amazon/lambda/powertools/logging/log4j/BufferingAppender.java

Lines 102 to 103 in 4e83d8a

	this.buffer = new KeyBuffer<>(maxBytes, event -> event.getMessage().getFormattedMessage().length(),
	this::logOverflowWarning);

powertools-lambda-java/powertools-logging/powertools-logging-log4j/src/main/java/software/amazon/lambda/powertools/logging/log4j/BufferingAppender.java

Lines 112 to 124 in 4e83d8a

	LambdaHandlerProcessor.getXrayTraceId().ifPresentOrElse(
	traceId -> {
	if (shouldBuffer(event.getLevel())) {
	bufferEvent(traceId, event);
	} else {
	callAppenders(event);
	}
	// Flush buffer on error logs if configured
	if (flushOnErrorLog && event.getLevel().isMoreSpecificThan(Level.WARN)) {
	flushBuffer(traceId);
	}
	},

Issue number: #2289

---

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.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud