Upgrade Guide

End of support v1

Given our commitment to all of our customers using Powertools for AWS Lambda (Java), we will keep Maven Central v1 releases and a v1 documentation archive to prevent any disruption.

Migrate to v2 from v1

We strongly encourage you to migrate to v2. Refer to our versioning policy to learn more about our version support process.

We've made minimal breaking changes to make your transition to v2 as smooth as possible.

Quick summary

The following table shows a summary of the changes made in v2 and whether code changes are necessary. Each change that requires a code change links to a section below explaining more details.

Area	Change	Code change required
Logging	The logging module was re-designed from scratch to support popular Java logging paradigms and libraries like log4j2, logback, and slf4j.	Yes
Metrics	Changed public interface to remove direct coupling with aws-embedded-metrics-java.	Yes
Tracing	Removed deprecated captureResponse and captureError options on @Tracing annotation.	Yes
Idempotency	The powertools-idempotency module was split by provider to improve modularity and reduce the deployment package size.	Yes
Idempotency	Updated IdempotencyConfig interface to support addition of response hooks.	No
Parameters	The powertools-parameters module was split by provider to improve modularity and reduce the deployment package size.	Yes
Batch Processing	Removed deprecated powertools-sqs module in favor of the more generic Batch Processing utility.	Yes
Batch Processing	Updated Batch Processing BatchMessageHandler interface to add support for parallel processing.	No
Validation	The @Validation utility returns 4xx error codes instead of 5xx error codes when used with API Gateway now.	No
Validation	Validating batch event sources now adds failed events as partial batch failures and does not fail the whole batch anymore.	No
Custom Resources	Removed deprecated Response.failed() and Response.success() methods.	Yes
Custom Resources	Changed interface of Response class to add an optional reason field.	No
Dependencies	Renamed powertools-core to powertools-common. This module should not be used as direct dependency and is listed here for completeness.	No
Dependencies	Removed org.aspectj.aspectjrt as project dependency in favor of consumers including the version they prefer.	Yes
Language support	Removed support for Java 8. The minimum required Java version is Java 11.	N/A

First Steps

Before you start, we suggest making a copy of your current working project or create a new branch with git.

1. Upgrade Java to at least version 11. While version 11 is supported, we recommend using the newest available LTS version of Java.
2. Review the following section to confirm if you need to make changes to your code.

Redesigned Logging Utility

The logging utility was re-designed from scratch to integrate better with Java idiomatic conventions and to remove the hard dependency on log4j as logging implementation. The new logging utility now supports slfj4 as logging interface and gives you the choice among log4j2 and logback as logging implementations. Consider the following steps to migrate from the v1 logging utility to the v2 logging utility:

1. Remove powertools-logging dependency and replace it with your logging backend of choice

In order to support different logging implementations, dedicated logging modules were created for the different logging implementations. Remove powertools-logging as a dependency and replace it with either powertools-logging-log4j or powertools-logging-logback.

<!-- BEFORE v2 -->
- <dependency>
-     <groupId>software.amazon.lambda</groupId>
-     <artifactId>powertools-logging</artifactId>
-     <version>1.x.x</version>
- </dependency>

<!-- AFTER v2 -->
+ <dependency>
+     <groupId>software.amazon.lambda</groupId>
+     <artifactId>powertools-logging-log4j</artifactId>
+     <version>2.x.x</version>
+ </dependency>

The AspectJ configuration still needs to depend on powertools-logging

We have only replaced the logging implementation dependency. The AspectJ configuration still needs to depend on powertools-logging which contains the main logic.

<aspectLibrary>
    <groupId>software.amazon.lambda</groupId>
    <artifactId>powertools-logging</artifactId>
</aspectLibrary>

2. Update log4j2.xml including new JsonTemplateLayout

This step is only required if you are using log4j2 as your logging implementation. The deprecated <LambdaJsonLayout/> element was removed. Replace it with the log4j2 agnostic <JsonTemplateLayout/> element.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <Console name="JsonAppender" target="SYSTEM_OUT">
-           <LambdaJsonLayout compact="true" eventEol="true"/>
+           <JsonTemplateLayout eventTemplateUri="classpath:LambdaJsonLayout.json" />
        </Console>
    </Appenders>
    <Loggers>
        <Logger name="JsonLogger" level="INFO" additivity="false">
            <AppenderRef ref="JsonAppender"/>
        </Logger>
        <Root level="info">
            <AppenderRef ref="JsonAppender"/>
        </Root>
    </Loggers>
</Configuration>

3. Migrate all logging specific calls to SLF4J native primitives (recommended)

The new logging utility is designed to integrate seamlessly with Java SLF4J to allow customers adopt Powertools Logging without large code refactorings. This improvement requires the migration of non-native SLF4J primitives from the v1 Logging utility.

While we recommend using SLF4J as a logging implementation independent facade, you can still use the log4j2 and logback interfaces directly.

Consider the following code example which gives you hints on how to achieve the same functionality between v1 and v2 Logging:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.lambda.powertools.logging.Logging;
// ... other imports

public class PaymentFunction implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
    // BEFORE v2: Uses org.apache.logging.log4j.LogManager
-   private static final Logger LOGGER = LogManager.getLogger(PaymentFunction.class);
    // AFTER v2: Use org.slf4j.LoggerFactory
+   private static final Logger LOGGER = LoggerFactory.getLogger(PaymentFunction.class);

    @Logging
    public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
        // ...

        // BEFORE v2: Uses LoggingUtils.appendKey to append custom global keys
        // LoggingUtils was removed!
-       LoggingUtils.appendKey("cardNumber", card.getId());
        // AFTER v2: Uses native SLF4J Mapped Diagnostic Context (MDC)
+       MDC.put("cardNumber", card.getId());

        // Regular logging has not changed
        LOGGER.info("My log message with argument.");

        // Adding custom keys on a specific log message
        // BEFORE v2: No direct way, only supported via LoggingUtils.appendKey and LoggingUtils.removeKey
        // AFTER v2: Extensive support for StructuredArguments
+       LOGGER.info("Collecting payment", StructuredArguments.entry("orderId", order.getId()));
        // { "message": "Collecting payment", ..., "orderId": 123}
        Map<String, String> customKeys = new HashMap<>();
        customKeys.put("paymentId", payment.getId());
        customKeys.put("amount", payment.getAmount);
+       LOGGER.info("Payment successful", StructuredArguments.entries(customKeys));
        // { "message": "Payment successful", ..., "paymentId": 123, "amount": 12.99}
    }
}

Make sure to learn more about the advanced structured argument serialization features in the Logging v2 documentation.

Updated Metrics utility interface

The Metrics utility is currently undergoing changes to the public interface as part of GitHub issue #1848. We will keep this upgrade guide updated with the most recent changes as soon as they are released. Stay tuned for updates!

Deprecated capture mode related @Tracing annotation parameters

The deprecated captureError and captureResponse arguments to the @Tracing annotation were removed in v2 and replaced by a new captureMode parameter. The parameter can be passed an Enum value of CaptureMode.

You should update your code using the new captureMode argument:

- @Tracing(captureError = false, captureResponse = false)
+ @Tracing(captureMode = CaptureMode.DISABLED)
public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
    // ...
}

Learn more about valid CaptureMode values in the Tracing documentation.

Idempotency utility split into sub-modules by provider

The Idempotency utility was split from the common powertools-idempotency package into individual packages for different persistence store providers. The main business logic is now in the powertools-idempotency-core package.

You should now include the powertools-idempotency-core package as an AspectJ library and the provider package like powertools-idempotency-dynamodb as a regular dependency.

<!-- BEFORE v2 -->
- <dependency>
-     <groupId>software.amazon.lambda</groupId>
-     <artifactId>powertools-idempotency</artifactId>
-     <version>1.x.x</version>
- </dependency>
<!-- AFTER v2 -->
<!-- In dependencies section -->
+ <dependency>
+     <groupId>software.amazon.lambda</groupId>
+     <artifactId>powertools-idempotency-dynamodb</artifactId>
+     <version>2.x.x</version>
+ </dependency>
<!-- In AspectJ configuration section -->
+ <aspectLibrary>
+     <groupId>software.amazon.lambda</groupId>
+     <artifactId>powertools-idempotency-core</artifactId>
+ </aspectLibrary>

Parameters utility split into sub-modules by provider

Parameters utilities were split from the common powertools-parameters package into individual packages for different parameter providers. You should now include the specific parameters dependency for your provider. If you use multiple providers, you can include multiple packages. Each parameter provider needs to be included as a dependency and an AspectJ library to use annotations.

This new structure reduces the bundle size of your deployment package.

<!-- BEFORE v2 -->
<!-- In dependencies section -->
- <dependency>
-     <groupId>software.amazon.lambda</groupId>
-     <artifactId>powertools-parameters</artifactId>
-     <version>1.x.x</version>
- </dependency>
<!-- In AspectJ configuration section -->
- <aspectLibrary>
-     <groupId>software.amazon.lambda</groupId>
-     <artifactId>powertools-parameters</artifactId>
- </aspectLibrary>
<!-- AFTER v2 -->
<!-- In dependencies section -->
+ <dependency>
+     <groupId>software.amazon.lambda</groupId>
+     <artifactId>powertools-parameters-secrets</artifactId>
+     <version>2.x.x</version>
+ </dependency>
<!-- ... your other providers -->
<!-- In AspectJ configuration section -->
+ <aspectLibrary>
+     <groupId>software.amazon.lambda</groupId>
+     <artifactId>powertools-parameters-secrets</artifactId>
+ </aspectLibrary>
<!-- ... your other providers -->

Find the full list of supported providers in the Parameters utility documentation.

Custom Resources updates the Response class

The Response class supporting CloudFormation Custom Resource implementations was updated to remove deprecated methods.

The Response.failed() and Response.success() methods without parameters were removed and require the physical resource ID now. You should update your code to use:

• Response.failed(String physicalResourceId)
• Response.success(String physicalResourceId)

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.CloudFormationCustomResourceEvent;
import software.amazon.lambda.powertools.cloudformation.AbstractCustomResourceHandler;
import software.amazon.lambda.powertools.cloudformation.Response;

public class MyCustomResourceHandler extends AbstractCustomResourceHandler {

    // ...

    @Override
    protected Response update(CloudFormationCustomResourceEvent updateEvent, Context context) {
+       String physicalResourceId = updateEvent.getPhysicalResourceId();
        UpdateResult updateResult = doUpdates(physicalResourceId);
        if (updateResult.isSuccessful()) {
-           return Response.success();
+           return Response.success(physicalResourceId);
        } else {
-           return Response.failed();
+           return Response.failed(physicalResourceId);
        }
    }

    // ...
}

Improved integration of Validation utility with other utilities

The Validation utility includes two updates that change the behavior of integration with other utilities and AWS services.

1. Updated HTTP status code when using @Validation with API Gateway

This does not require a code change in the Lambda function using the Validation utility but might impact how your calling application treats exceptions. Prior to v2, a 500 HTTP status code was returned when the validation did not pass. Consistent with the HTTP specification, a 400 status code is returned now indicating a user error instead of a server error.

Consider the following example:

import software.amazon.lambda.powertools.validation.Validation;

public class MyFunctionHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

    @Override
    @Validation(inboundSchema = "classpath:/schema_in.json", outboundSchema = "classpath:/schema_out.json")
    public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
        // ...
        return something;
    }
}

If the request validation fails, you can expect the following change in the HTTP response status code on the client-side:

# BEFORE v2: 500 Internal Server Error
❯ curl -s -o /dev/null -w "%{http_code}" https://{API_ID}.execute-api.{REGION}.amazonaws.com/{STAGE}/{PATH}
500
# AFTER v2: 400 Bad Request
❯ curl -s -o /dev/null -w "%{http_code}" https://{API_ID}.execute-api.{REGION}.amazonaws.com/{STAGE}/{PATH}
400

2. Integration with partial batch failures when using Batch utility

This does not require a code change but might affect the batch processing flow when using the Validation utility in combination with the Batch processing utility.

Consider the following example:

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.events.SQSBatchResponse;
import com.amazonaws.services.lambda.runtime.events.SQSEvent;
import software.amazon.lambda.powertools.batch.BatchMessageHandlerBuilder;
import software.amazon.lambda.powertools.batch.handler.BatchMessageHandler;

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
    @Validation(inboundSchema = "classpath:/schema_in.json", outboundSchema = "classpath:/schema_out.json")
    public SQSBatchResponse handleRequest(SQSEvent sqsEvent, Context context) {
        return handler.processBatch(sqsEvent, context);
    }

    private void processMessage(Product p, Context c) {
        // Process the product
    }
}

• Prior to v2 this caused the whole batch to fail.
• After v2 this will add only the failed events to the batch item failure list in the response and process the remaining messages.

Check if your workload can tolerate this behavior and make sure it is designed for idempotency when using partial batch item failures. We offer the Idempotency utility to simplify integration of idempotent behavior in your workloads.

AspectJ runtime not included by default anymore

The AspectJ runtime is no longer included as a transitive dependency of Powertools. For all utilities offering annotations using AspectJ compile-time weaving, you need to include the AspectJ runtime yourself now. This is also documented, with a complete example, in our installation guide. For Maven projects, make sure to add the following dependency in your dependencies section:

+ <dependency>
+     <groupId>org.aspectj</groupId>
+     <artifactId>aspectjrt</artifactId>
+     <version>1.9.22</version>
+ </dependency>

Removed powertools-sqs module in favor of powertools-batch

The archived documentation contains a migration guide for both large message handling using powertools-sqs and batch processing using powertools-sqs. The sections below explain the high-level steps for your convenience.

Migrating SQS Batch processing (@SqsBatch)

The batch processing library provides a way to process messages and gracefully handle partial failures for SQS, Kinesis Streams, and DynamoDB Streams batch sources. In comparison to the legacy SQS Batch library, it relies on Lambda partial batch responses, which allows the library to provide a simpler, more reliable interface for processing batches.

In order to get started, check out the new processing messages from SQS documentation. In most cases, you will simply be able to retain your existing batch message handler function, and wrap it with the new batch processing interface. Unlike the powertools-sqs module, the new powertools-batch module uses partial batch responses to communicate to Lambda which messages have been processed and must be removed from the queue. The return value of the handler's process function must be returned to Lambda.

The new library also no longer requires the SQS:DeleteMessage action on the Lambda function's role policy, as Lambda itself now manages removal of messages from the queue.

Some tuneables from powertools-sqs are no longer provided.

• Non-retryable Exceptions - there is no mechanism to indicate in a partial batch response that a particular message should not be retried and instead moved to DLQ - a message either succeeds, or fails and is retried. A message will be moved to the DLQ once the normal retry process has expired.
• Suppress Exception - The new batch processor does not throw an exception on failure of a handler. Instead, its result must be returned by your code from your message handler to Lambda, so that Lambda can manage the completed messages and retry behaviour.

Migrating SQS Large message handling (@SqsLargeMessage)

• Replace the dependency in Maven / Gradle: powertools-sqs ==> powertools-large-messages
• Replace the annotation: @SqsLargeMessage ==> @LargeMessage (the new module handles both SQS and SNS)
• Move the annotation away from the Lambda handleRequest method and put it on a method with SQSEvent.SQSMessage or SNSEvent.SNSRecord as first parameter.
• The annotation now handles a single message, contrary to the previous version that was handling the complete batch. This gives more control, especially when dealing with partial failures with SQS (see the batch module).
• The new module only provides an annotation: an equivalent to the SqsUtils class is not available anymore in this new version.