AWS powertools documentation change
Summary
Updated example code to show MetricsBuilder configuration and manual flushing
Security assessment
Demonstrates alternative implementation patterns without security-specific context.
Diff
diff --git a/powertools/java/latest/core/metrics.md b/powertools/java/latest/core/metrics.md index 69d2911b0..8fc7a5bf1 100644 --- a//powertools/java/latest/core/metrics.md +++ b//powertools/java/latest/core/metrics.md @@ -22,0 +23 @@ Initializing search + * [ Usage patterns ](../../usage-patterns/) @@ -174,0 +176 @@ MavenGradle + 49 @@ -184 +186 @@ MavenGradle - <version>2.5.0</version> + <version>2.7.0</version> @@ -189,0 +192 @@ MavenGradle + <!-- Note: This AspectJ configuration is not needed when using the functional approach --> @@ -246,0 +250 @@ MavenGradle + 16 @@ -253 +257 @@ MavenGradle - id 'io.freefair.aspectj.post-compile-weaving' version '8.1.0' + id 'io.freefair.aspectj.post-compile-weaving' version '8.1.0' // Not needed when using the functional approach @@ -261 +265,2 @@ MavenGradle - aspect 'software.amazon.lambda:powertools-metrics:2.5.0' + aspect 'software.amazon.lambda:powertools-metrics:2.7.0' // Not needed when using the functional approach + implementation 'software.amazon.lambda:powertools-metrics:2.7.0' // Use this instead of 'aspect' when using the functional approach @@ -297 +302 @@ For most use-cases, we recommend using Environment variables and only overwrite -template.yamlMetricsEnabledHandler.java +@FlushMetrics annotationMetricsBuilderEnvironment variables @@ -309,0 +315,3 @@ template.yamlMetricsEnabledHandler.java + 11 + 12 + 13 @@ -314,10 +322,13 @@ template.yamlMetricsEnabledHandler.java - Resources: - HelloWorldFunction: - Type: AWS::Serverless::Function - Properties: - ... - Runtime: java11 - Environment: - Variables: - POWERTOOLS_SERVICE_NAME: payment - POWERTOOLS_METRICS_NAMESPACE: ServerlessAirline + import software.amazon.lambda.powertools.metrics.FlushMetrics; + import software.amazon.lambda.powertools.metrics.MetricsFactory; + + public class MetricsEnabledHandler implements RequestHandler<Object, Object> { + + private static final Metrics metrics = MetricsFactory.getMetricsInstance(); + + @Override + @FlushMetrics(namespace = "ServerlessAirline", service = "payment") + public Object handleRequest(Object input, Context context) { + // ... + } + } @@ -341,0 +353,3 @@ template.yamlMetricsEnabledHandler.java + 14 + 15 + 16 @@ -346,2 +360,2 @@ template.yamlMetricsEnabledHandler.java - import software.amazon.lambda.powertools.metrics.FlushMetrics; - import software.amazon.lambda.powertools.metrics.MetricsFactory; + import software.amazon.lambda.powertools.metrics.Metrics; + import software.amazon.lambda.powertools.metrics.MetricsBuilder; @@ -351 +365,4 @@ template.yamlMetricsEnabledHandler.java - private static final Metrics metrics = MetricsFactory.getMetricsInstance(); + private static final Metrics metrics = MetricsBuilder.builder() + .withNamespace("ServerlessAirline") + .withService("payment") + .build(); @@ -354 +370,0 @@ template.yamlMetricsEnabledHandler.java - @FlushMetrics(namespace = "ServerlessAirline", service = "payment") @@ -356,0 +373 @@ template.yamlMetricsEnabledHandler.java + metrics.flush(); @@ -363 +379,0 @@ template.yamlMetricsEnabledHandler.java -`Metrics` is implemented as a Singleton to keep track of your aggregate metrics in memory and make them accessible anywhere in your code. To guarantee that metrics are flushed properly the `@FlushMetrics` annotation must be added on the lambda handler. @@ -365 +381,31 @@ template.yamlMetricsEnabledHandler.java -You can use the Metrics utility without the `@FlushMetrics` annotation and flush manually. Read more in the advanced section below. + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + +| + + + Resources: + HelloWorldFunction: + Type: AWS::Serverless::Function + Properties: + ... + Runtime: java11 + Environment: + Variables: + POWERTOOLS_SERVICE_NAME: payment + POWERTOOLS_METRICS_NAMESPACE: ServerlessAirline + + +---|--- + +`Metrics` is implemented as a Singleton to keep track of your aggregate metrics in memory and make them accessible anywhere in your code. The `@FlushMetrics` annotation automatically flushes metrics at the end of the Lambda handler execution. Alternatively, you can use the functional approach and manually flush metrics using `metrics.flush()`. + +Read more about the functional approach in the advanced section below. @@ -728 +774 @@ Info -Adding metadata with a key that is the same as an existing metric will be ignored +Adding metadata with a key that is the same as an existing metric will be ignored. @@ -944 +990 @@ Generally, this would be an edge case since you [pay for unique metric](https:// -The `Metrics` Singleton provides all configuration options via `MetricsBuilder` in addition to the `@FlushMetrics` annotation. This can be useful if work in an environment or framework that does not leverage the vanilla Lambda `handleRequest` method. +You can use the **functional API** approach (see [usage patterns](../../usage-patterns/#functional-approach)) to work with Metrics without the `@FlushMetrics` annotation. The `Metrics` Singleton provides all configuration options via `MetricsBuilder`. This approach eliminates the AspectJ runtime dependency and is useful if you work in an environment or with a framework that does not leverage the vanilla Lambda `handleRequest` method. @@ -948 +994 @@ The environment variables for Service and Namespace configuration still apply bu -The following example shows how to configure a custom `Metrics` Singleton using the Builder pattern. Note that it is necessary to manually flush metrics now. +The following example shows how to configure a custom `Metrics` Singleton using the Builder pattern. With the functional approach, you must manually flush metrics using `metrics.flush()`. @@ -977,0 +1024 @@ App.java + 26 @@ -988 +1035 @@ App.java - // Create and configure a Metrics singleton without annotation + // Create and configure a Metrics singleton using the functional approach @@ -1002 +1049 @@ App.java - // Add metrics to the custom metrics singleton + // Add metrics @@ -1003,0 +1051 @@ App.java + // Manually flush metrics @@ -1258 +1306 @@ Consider the following example where we redirect the standard output to a custom -2025-10-02 +2025-11-13