AWS powertools medium security documentation change
Summary
Updated documentation for AWS Lambda Powertools Tracing with version 2.7.0, added functional API examples, clarified capture modes, and improved AWS SDK instrumentation guidance
Security assessment
The changes introduce explicit guidance about controlling sensitive data capture in traces through environment variables (POWERTOOLS_TRACER_CAPTURE_RESPONSE/POWERTOOLS_TRACER_CAPTURE_ERROR) and captureMode settings. This addresses data exposure risks by allowing developers to disable automatic capture of responses/errors containing sensitive information. The added warning note about returning sensitive information directly references security implications.
Diff
diff --git a/powertools/java/latest/core/tracing.md b/powertools/java/latest/core/tracing.md index 22ce1fe13..fa490e4b9 100644 --- a//powertools/java/latest/core/tracing.md +++ b//powertools/java/latest/core/tracing.md @@ -22,0 +23 @@ Initializing search + * [ Usage patterns ](../../usage-patterns/) @@ -35 +36,2 @@ Initializing search - * Utilities + * Advanced usage + * Multi-threaded programming @@ -36,0 +39 @@ Initializing search + * AWS SDK for Java 2.x @@ -66 +69,2 @@ Table of contents - * Utilities + * Advanced usage + * Multi-threaded programming @@ -67,0 +72 @@ Table of contents + * AWS SDK for Java 2.x @@ -142,0 +148 @@ MavenGradle + 49 @@ -152 +158 @@ MavenGradle - <version>2.5.0</version> + <version>2.7.0</version> @@ -157,0 +164 @@ MavenGradle + <!-- Note: This AspectJ configuration is not needed when using the functional approach --> @@ -214,0 +222 @@ MavenGradle + 16 @@ -221 +229 @@ 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 @@ -229 +237,2 @@ MavenGradle - aspect 'software.amazon.lambda:powertools-tracing:2.5.0' + aspect 'software.amazon.lambda:powertools-tracing:2.7.0' // Not needed when using the functional approach + implementation 'software.amazon.lambda:powertools-tracing:2.7.0' // Use this instead of 'aspect' when using the functional approach @@ -232,2 +241,2 @@ MavenGradle - sourceCompatibility = 11 - targetCompatibility = 11 + sourceCompatibility = 11 // or higher + targetCompatibility = 11 // or higher @@ -281 +290,3 @@ The Powertools for AWS Lambda (Java) service name is used as the X-Ray namespace -To enable Powertools for AWS Lambda (Java) tracing to your function add the `@Tracing` annotation to your `handleRequest` method or on any method will capture the method as a separate subsegment automatically. You can optionally choose to customize segment name that appears in traces. +You can enable tracing using either the `@Tracing` annotation or the functional API. + +**With the`@Tracing` annotation**, add it to your `handleRequest` method or any method to capture it as a separate subsegment automatically. You can optionally customize the segment name that appears in traces. @@ -283 +294,3 @@ To enable Powertools for AWS Lambda (Java) tracing to your function add the `@Tr -Tracing annotationCustom Segment names +**With the functional API** , use `TracingUtils.withSubsegment()` to manually create subsegments without AspectJ configuration. + +@Tracing annotationFunctional APICustom Segment names @@ -329,0 +343,37 @@ Tracing annotationCustom Segment names +---|--- + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + +| + + + import software.amazon.lambda.powertools.tracing.TracingUtils; + + public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> { + + public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) { + TracingUtils.withSubsegment("businessLogic1", subsegment -> { + // Business logic 1 + }); + + TracingUtils.withSubsegment("businessLogic2", subsegment -> { + // Business logic 2 + }); + } + } + + @@ -353 +403 @@ Tracing annotationCustom Segment names -When using this `@Tracing` annotation, Utility performs these additional tasks to ease operations: +When using the `@Tracing` annotation, the utility performs these additional tasks to ease operations: @@ -361 +411,3 @@ When using this `@Tracing` annotation, Utility performs these additional tasks t -By default, this annotation will automatically record method responses and exceptions. You can change the default behavior by setting the environment variables `POWERTOOLS_TRACER_CAPTURE_RESPONSE` and `POWERTOOLS_TRACER_CAPTURE_ERROR` as needed. Optionally, you can override behavior by different supported `captureMode` to record response, exception or both. +By default, the `@Tracing` annotation uses `captureMode=ENVIRONMENT_VAR`, which means it will only record method responses and exceptions if you set the environment variables `POWERTOOLS_TRACER_CAPTURE_RESPONSE` and `POWERTOOLS_TRACER_CAPTURE_ERROR` to `true`. You can override this behavior by specifying a different `captureMode` to always record response, exception, both, or neither. + +Note @@ -363 +415 @@ By default, this annotation will automatically record method responses and excep -Returning sensitive information from your Lambda handler or functions, where `Tracing` is used? +When using the functional API with `TracingUtils.withSubsegment()`, response and exception capture is not automatic. You can manually add metadata using `TracingUtils.putMetadata()` as needed. @@ -365 +417 @@ Returning sensitive information from your Lambda handler or functions, where `Tr -You can disable annotation from capturing their responses and exception as tracing metadata with **`captureMode=DISABLED`** or globally by setting environment variables **`POWERTOOLS_TRACER_CAPTURE_RESPONSE`** and **`POWERTOOLS_TRACER_CAPTURE_ERROR`** to **`false`** +Returning sensitive information from your Lambda handler or functions? @@ -367 +419,3 @@ You can disable annotation from capturing their responses and exception as traci -Disable on annotationDisable Globally +When using the `@Tracing` annotation, you can disable it from capturing responses and exceptions as tracing metadata with **`captureMode=DISABLED`** or globally by setting the environment variables **`POWERTOOLS_TRACER_CAPTURE_RESPONSE`** and **`POWERTOOLS_TRACER_CAPTURE_ERROR`** to **`false`**. When using the functional API, you have full control over what metadata is captured. + +@Tracing annotation - Disable on method@Tracing annotation - Disable GloballyFunctional API @@ -420,0 +475,27 @@ Disable on annotationDisable Globally +---|--- + + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + +| + + + import software.amazon.lambda.powertools.tracing.TracingUtils; + + public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> { + + public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) { + TracingUtils.withSubsegment("businessLogic", subsegment -> { + // With functional API, you control what metadata is captured + }); + } + + @@ -550,35 +631 @@ App.java -## Utilities¶ - -Tracing modules comes with certain utility method when you don't want to use annotation for capturing a code block under a subsegment, or you are doing multithreaded programming. Refer examples below. - -Functional ApiMulti Threaded Programming - - - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 - -| - - - import software.amazon.lambda.powertools.tracing.Tracing; - import software.amazon.lambda.powertools.tracing.TracingUtils; - - public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> { - - public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) { - TracingUtils.withSubsegment("loggingResponse", subsegment -> { - // Some business logic - }); +## Advanced usage¶ @@ -586,5 +633 @@ Functional ApiMulti Threaded Programming - TracingUtils.withSubsegment("localNamespace", "loggingResponse", subsegment -> { - // Some business logic - }); - } - } +### Multi-threaded programming¶ @@ -591,0 +635 @@ Functional ApiMulti Threaded Programming +When working with multiple threads, you need to pass the trace entity to ensure proper trace context propagation. @@ -593 +637 @@ Functional ApiMulti Threaded Programming ----|--- +Multi-threaded example @@ -632 +676,5 @@ Functional ApiMulti Threaded Programming -Powertools for Lambda (Java) cannot intercept SDK clients instantiation to add X-Ray instrumentation. You should make sure to instrument the SDK clients explicitly. Refer details on [how to instrument SDK client with Xray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html#xray-sdk-java-awssdkclients) and [outgoing http calls](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html#xray-sdk-java-httpclients). For example: +### AWS SDK for Java 2.x¶ + +Powertools for AWS Lambda (Java) includes the `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` library, which **automatically instruments all AWS SDK v2 clients** when you add the `powertools-tracing` dependency to your project. This means downstream calls to AWS services are traced without any additional configuration. + +If you need more control over which clients are instrumented, you can manually add the `TracingInterceptor` to specific clients: @@ -634 +682 @@ Powertools for Lambda (Java) cannot intercept SDK clients instantiation to add X -LambdaHandler.java +Manual instrumentation (optional) @@ -646,0 +695,4 @@ LambdaHandler.java + 11 + 12 + 13 + 14 @@ -651,2 +703,3 @@ LambdaHandler.java - import com.amazonaws.xray.AWSXRay;