AWS powertools documentation change
Summary
Added documentation about concurrency models, X-Ray trace propagation, updated dependency version (2.7.0 → 2.8.0), and Java 21 virtual threads guidance
Security assessment
The change adds security-adjacent documentation about X-Ray trace context propagation in parallel processing, which helps maintain security visibility through proper tracing. However, there's no evidence of addressing a specific security vulnerability. The version bump might include security improvements but isn't explicitly stated.
Diff
diff --git a/powertools/java/latest/utilities/batch.md b/powertools/java/latest/utilities/batch.md index febfcceef..6bd07ae29 100644 --- a//powertools/java/latest/utilities/batch.md +++ b//powertools/java/latest/utilities/batch.md @@ -41,0 +42,3 @@ Initializing search + * Choosing the right concurrency model + * Without custom executor (parallelStream) + * With custom executor (CompletableFuture) @@ -67,0 +71,3 @@ Table of contents + * Choosing the right concurrency model + * Without custom executor (parallelStream) + * With custom executor (CompletableFuture) @@ -157 +163 @@ MavenGradle - <version>2.7.0</version> + <version>2.8.0</version> @@ -182 +188 @@ MavenGradle - implementation 'software.amazon.lambda:powertools-batch:2.7.0' + implementation 'software.amazon.lambda:powertools-batch:2.8.0' @@ -902 +908 @@ Info -To get more threads available (more vCPUs), you need to increase the amount of memory allocated to your Lambda function. While it is possible to increase the number of threads using Java options or custom thread pools, in most cases the defaults work well, and changing them is more likely to decrease performance (see [here](https://www.baeldung.com/java-when-to-use-parallel-stream#fork-join-framework) and [here](https://dzone.com/articles/be-aware-of-forkjoinpoolcommonpool)). In situations where this may be useful - such as performing IO-bound work in parallel - make sure to measure before and after! +To get more threads available (more vCPUs), you need to increase the amount of memory allocated to your Lambda function. While it is possible to increase the number of threads using Java options or custom thread pools, in most cases the defaults work well, and changing them is more likely to decrease performance (see [here](https://www.baeldung.com/java-when-to-use-parallel-stream#fork-join-framework) and [here](https://dzone.com/articles/be-aware-of-forkjoinpoolcommonpool)). In situations where this may be useful, such as performing IO-bound work in parallel, make sure to measure before and after! @@ -904 +910,3 @@ To get more threads available (more vCPUs), you need to increase the amount of m -Example with SQSExample with SQS (using custom executor) +When using parallel processing with X-Ray tracing enabled, the Tracing utility automatically handles trace context propagation to worker threads. This ensures that subsegments created during parallel message processing appear under the correct parent segment in your X-Ray trace, maintaining proper trace hierarchy and visibility into your batch processing performance. + +Example with SQSExample with SQS (using custom executor)Example with X-Ray Tracing @@ -1003,0 +1012,132 @@ Example with SQSExample with SQS (using custom executor) + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + +| + + + public class SqsBatchHandler implements RequestHandler<SQSEvent, SQSBatchResponse> { + + private final BatchMessageHandler<SQSEvent, SQSBatchResponse> handler; + + public SqsBatchHandler() { + handler = new BatchMessageHandlerBuilder() + .withSqsBatchHandler() + .buildWithMessageHandler(this::processMessage, Product.class); + } + + @Override + @Tracing + public SQSBatchResponse handleRequest(SQSEvent sqsEvent, Context context) { + return handler.processBatchInParallel(sqsEvent, context); + } + + @Tracing // This will appear correctly under the handleRequest subsegment + private void processMessage(Product p, Context c) { + // Process the product - subsegments will appear under handleRequest + } + } + + +---|--- + +### Choosing the right concurrency model¶ + +The `processBatchInParallel` method has two overloads with different concurrency characteristics: + +#### Without custom executor (parallelStream)¶ + +When you call `processBatchInParallel(event, context)` without providing an executor, the implementation uses Java's `parallelStream()` which leverages the common `ForkJoinPool`. + +**Best for: CPU-bound workloads** + + * Thread pool size matches available CPU cores + * Optimized for computational tasks (data transformation, calculations, parsing) + * Main thread participates in work-stealing + * Simple to use with no configuration needed + + + + + 1 + 2 + +| + + + // Good for CPU-intensive processing + return handler.processBatchInParallel(sqsEvent, context); + + +---|--- + +#### With custom executor (CompletableFuture)¶ + +When you call `processBatchInParallel(event, context, executor)` with a custom executor, the implementation uses `CompletableFuture` which gives you full control over the thread pool. + +**Best for: I/O-bound workloads** + + * You control thread pool size and characteristics + * Ideal for I/O operations (HTTP calls, database queries, S3 operations) + * Can use larger thread pools since threads spend time waiting, not computing + * Main thread only waits; worker threads do all processing + + + + + 1 + 2 + 3 + +| + + + // Good for I/O-intensive processing (API calls, DB queries, etc.) + ExecutorService executor = Executors.newFixedThreadPool(50); + return handler.processBatchInParallel(sqsEvent, context, executor); + + +---|--- + +**For Java 21+: Virtual Threads** + +If you're using Java 21 or later, virtual threads are ideal for I/O-bound workloads: + + + 1 + 2 + +| + + + ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor(); + return handler.processBatchInParallel(sqsEvent, context, executor); + + +---|--- + +Virtual threads are lightweight and can handle thousands of concurrent I/O operations efficiently without the overhead of platform threads. + +**Recommendation for typical Lambda SQS processing:** + +Most Lambda functions processing SQS messages perform I/O operations (calling APIs, querying databases, writing to S3). For these workloads, use the custom executor approach with a thread pool sized appropriately for your I/O operations or virtual threads for Java 21+. + @@ -1148 +1288 @@ Both raw and deserialized message handlers can choose to take the Lambda context -2025-11-13 +2025-11-21