feat(metrics): introduce MetricUtils.withMetric utility

closes aws-powertools#999

Author: humanzz

docs/core/metrics.md

@@ -233,4 +233,28 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `withSingle
             });
         }
     }
+    ```
+
+## Creating metrics with different configurations
+
+Use `withMetric` if you have one or more metrics that should have different configurations e.g. dimensions or namespace.
+
+=== "App.java"
+
+    ```java hl_lines="7 8 9 10 11 12 13" 
+    import static software.amazon.lambda.powertools.metrics.MetricsUtils.withSingleMetric;
+
+    public class App implements RequestHandler<Object, Object> {
+
+        @Override
+        public Object handleRequest(Object input, Context context) {
+             withMetric(metric -> {
+                // override default dimensions
+                metric.setDimensions(DimensionSet.of("AnotherService", "CustomService"));
+                // add metrics
+                metric.putMetric("CustomMetrics1", 1, Unit.COUNT);
+                metric.putMetric("CustomMetrics2", 5, Unit.COUNT);
+            });
+        }
+    }
     ```

powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsUtils.java

@@ -121,6 +121,26 @@ public static void withSingleMetric(final String name,
         }
     }
 
+    /**
+     * Provide and immediately flush a {@link MetricsLogger}. It will use the default namespace
+     * specified either on {@link Metrics} annotation or via POWERTOOLS_METRICS_NAMESPACE env var.
+     * It by default captures function_request_id as property if used together with {@link Metrics} annotation. It will also
+     * capture xray_trace_id as property if tracing is enabled.
+     *
+     * @param logger the MetricsLogger
+     */
+    public static void withMetric(final Consumer<MetricsLogger> logger) {
+        MetricsLogger metricsLogger = logger();
+
+        try {
+            metricsLogger.setNamespace(defaultNameSpace());
+            captureRequestAndTraceId(metricsLogger);
+            logger.accept(metricsLogger);
+        } finally {
+            metricsLogger.flush();
+        }
+    }
+
     public static DimensionSet[] getDefaultDimensions() {
         return Arrays.copyOf(defaultDimensions, defaultDimensions.length);
     }

powertools-metrics/src/test/java/software/amazon/lambda/powertools/metrics/MetricsLoggerTest.java

@@ -123,6 +123,38 @@ void singleMetricsCaptureUtilityWithDefaultNameSpace() {
         }
     }
 
+    @Test
+    void metricsCaptureUtilityWithDefaultNameSpace() {
+        try (MockedStatic<SystemWrapper> mocked = mockStatic(SystemWrapper.class);
+             MockedStatic<software.amazon.lambda.powertools.core.internal.SystemWrapper> internalWrapper = mockStatic(software.amazon.lambda.powertools.core.internal.SystemWrapper.class)) {
+            mocked.when(() -> SystemWrapper.getenv("AWS_EMF_ENVIRONMENT")).thenReturn("Lambda");
+            mocked.when(() -> SystemWrapper.getenv("POWERTOOLS_METRICS_NAMESPACE")).thenReturn("GlobalName");
+            internalWrapper.when(() -> getenv("_X_AMZN_TRACE_ID")).thenReturn("Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1\"");
+
+            MetricsUtils.withMetric(metricsLogger -> {
+                metricsLogger.setDimensions(DimensionSet.of("Dimension1", "Value1"));
+                metricsLogger.putMetric("Metric1", 1, Unit.COUNT);
+            });
+
+            assertThat(out.toString())
+                    .satisfies(s -> {
+                        Map<String, Object> logAsJson = readAsJson(s);
+
+                        assertThat(logAsJson)
+                                .containsEntry("Metric1", 1.0)
+                                .containsEntry("Dimension1", "Value1")
+                                .containsKey("_aws")
+                                .containsEntry("xray_trace_id", "1-5759e988-bd862e3fe1be46a994272793");
+
+                        Map<String, Object> aws = (Map<String, Object>) logAsJson.get("_aws");
+
+                        assertThat(aws.get("CloudWatchMetrics"))
+                                .asString()
+                                .contains("Namespace=GlobalName");
+                    });
+        }
+    }
+
     @Test
     void shouldThrowExceptionWhenDefaultDimensionIsNull() {
         assertThatNullPointerException()