Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(v2): document use of aws-crt-client (#1092) #1605

Merged
merged 14 commits into from
Mar 21, 2024
Merged

chore(v2): document use of aws-crt-client (#1092) #1605

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
4036d07
chore(v2): document use of aws-crt-client (#1092)
jreijn Mar 14, 2024
9715ca8
Update docs/FAQs.md
jreijn Mar 17, 2024
ffdf3cf
Update docs/FAQs.md
jreijn Mar 17, 2024
feb3600
Update docs/FAQs.md
jreijn Mar 17, 2024
6985d0a
chore(v2): improve documentation based on feedback (#1092)
jreijn Mar 17, 2024
3ee1ac9
Update docs/FAQs.md
jreijn Mar 18, 2024
9997dec
Update docs/FAQs.md
jreijn Mar 18, 2024
1d475be
Update docs/FAQs.md
jreijn Mar 18, 2024
7d9caed
Update docs/FAQs.md
jreijn Mar 18, 2024
712e84a
Update docs/FAQs.md
jreijn Mar 18, 2024
1eae687
Update docs/FAQs.md
jreijn Mar 18, 2024
6a168e6
Update docs/FAQs.md
jreijn Mar 18, 2024
0e42949
Update docs/FAQs.md
jreijn Mar 18, 2024
0eb8249
Update FAQs.md and set version
jreijn Mar 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 98 additions & 2 deletions docs/FAQs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Frequently Asked Questions

## How can I use Powertools for AWS Lambda (Java) with Lombok?

Poweretools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. In case you want to use `Lombok` or other compile-time preprocessor for your project, it is required to change `aspectj-maven-plugin` configuration to enable in-place weaving feature. Otherwise the plugin will ignore changes introduced by `Lombok` and will use `.java` files as a source.
Powertools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. In case you want to use `Lombok` or other compile-time preprocessor for your project, it is required to change `aspectj-maven-plugin` configuration to enable in-place weaving feature. Otherwise the plugin will ignore changes introduced by `Lombok` and will use `.java` files as a source.

To enable in-place weaving feature you need to use following `aspectj-maven-plugin` configuration:

Expand All @@ -29,7 +29,7 @@ To enable in-place weaving feature you need to use following `aspectj-maven-plug

## How can I use Powertools for AWS Lambda (Java) with Kotlin projects?

Poweretools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. When using it with Kotlin projects, it is required to `forceAjcCompile`.
Powertools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. When using it with Kotlin projects, it is required to `forceAjcCompile`.
No explicit configuration should be required for gradle projects.

To enable `forceAjcCompile` you need to use following `aspectj-maven-plugin` configuration:
Expand All @@ -47,3 +47,99 @@ To enable `forceAjcCompile` you need to use following `aspectj-maven-plugin` con
</configuration>
```

## How can I use Powertools for AWS Lambda (Java) with the AWS CRT HTTP Client?

Powertools uses the `url-connection-client` as the default HTTP client. The `url-connection-client` is a lightweight HTTP client, which keeps the impact on Lambda cold starts to a minimum.
With the [announcement](https://aws.amazon.com/blogs/developer/announcing-availability-of-the-aws-crt-http-client-in-the-aws-sdk-for-java-2-x/) of the `aws-crt-client` a new HTTP client has been released, which offers faster SDK startup time and smaller memory footprint.

Unfortunately, replacing the `url-connection-client` dependency with the `aws-crt-client` will not immediately improve the lambda cold start performance and memory footprint,
as the default version of the dependency contains native system libraries for all supported runtimes and architectures (Linux, MacOS, Windows, AMD64, ARM64, etc). This makes the CRT client portable, without the user having to consider _where_ their code will run, but comes at the cost of JAR size.

### Configuring dependencies

Using the `aws-crt-client` in your project requires the exclusion of the `url-connection-client` transitive dependency from the powertools dependency.

```xml
<dependency>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-parameters</artifactId>
<version>2.0.0</version>
<exclusions>
<exclusion>
<groupId>software.amazon.awssdk</groupId>
<artifactId>url-connection-client</artifactId>
</exclusion>
</exclusions>
</dependency>
```
Next, add the `aws-crt-client` and exclude the "generic" `aws-crt` dependency (contains all runtime libraries).
Instead, set a specific classifier of the `aws-crt` to use the one for your target runtime: either `linux-x86_64` for a Lambda configured for x86 or `linux-aarch_64` for Lambda using arm64.

!!! note "You will need to add a separate maven profile to build and debug locally when your development environment does not share the target architecture you are using in Lambda."
By specifying the specific target runtime, we prevent other target runtimes from being included in the jar file, resulting in a smaller Lambda package and improved cold start times.

```xml

<dependencies>
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>aws-crt-client</artifactId>
<version>2.23.21</version>
<exclusions>
<exclusion>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
<version>0.29.9</version>
<classifier>linux-x86_64</classifier>
</dependency>
</dependencies>
```

### Explicitly set the AWS CRT HTTP Client
After configuring the dependencies, it's required to explicitly specify the AWS SDK HTTP client.
Depending on the Powertools module, there is a different way to configure the SDK client.

The following example shows how to use the Lambda Powertools Parameters module while leveraging the AWS CRT Client.

```java hl_lines="11-16 19-20 22"
import static software.amazon.lambda.powertools.parameters.transform.Transformer.base64;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.services.ssm.SsmClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.lambda.powertools.parameters.ssm.SSMProvider;

public class RequestHandlerWithParams implements RequestHandler<String, String> {

// Get an instance of the SSMProvider with a custom HTTP client (aws crt).
SSMProvider ssmProvider = SSMProvider
.builder()
.withClient(
SsmClient.builder()
.httpClient(AwsCrtHttpClient.builder().build())
.build()
)
.build();

public String handleRequest(String input, Context context) {
// Retrieve a single param
String value = ssmProvider
.get("/my/secret");
// We might instead want to retrieve multiple parameters at once, returning a Map of key/value pairs
// .getMultiple("/my/secret/path");

// Return the result
return value;
}
}
```
The `aws-crt-client` was considered for adoption as the default HTTP client in Lambda Powertools for Java as mentioned in [Move SDK http client to CRT](https://github.com/aws-powertools/powertools-lambda-java/issues/1092),
but due to the impact on the developer experience it was decided to stick with the `url-connection-client`.
26 changes: 13 additions & 13 deletions docs/utilities/batch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -530,19 +530,19 @@ Handlers can be provided when building the batch processor and are available for
For instance for DynamoDB:

```java
BatchMessageHandler<DynamodbEvent, StreamsEventResponse> handler = new BatchMessageHandlerBuilder()
.withDynamoDbBatchHandler()
.withSuccessHandler((m) -> {
// Success handler receives the raw message
LOGGER.info("Message with sequenceNumber {} was successfully processed",
m.getDynamodb().getSequenceNumber());
})
.withFailureHandler((m, e) -> {
// Failure handler receives the raw message and the exception thrown.
LOGGER.info("Message with sequenceNumber {} failed to be processed: {}"
, e.getDynamodb().getSequenceNumber(), e);
})
.buildWithMessageHander(this::processMessage);
BatchMessageHandler<DynamodbEvent, StreamsEventResponse> handler = new BatchMessageHandlerBuilder()
.withDynamoDbBatchHandler()
.withSuccessHandler((m) -> {
// Success handler receives the raw message
LOGGER.info("Message with sequenceNumber {} was successfully processed",
m.getDynamodb().getSequenceNumber());
})
.withFailureHandler((m, e) -> {
// Failure handler receives the raw message and the exception thrown.
LOGGER.info("Message with sequenceNumber {} failed to be processed: {}"
, e.getDynamodb().getSequenceNumber(), e);
})
.buildWithMessageHander(this::processMessage);
```

!!! info
Expand Down
85 changes: 43 additions & 42 deletions docs/utilities/large_messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,48 +97,49 @@ of amazon-sns-java-extended-client-lib.
Depending on your version of Java (either Java 1.8 or 11+), the configuration slightly changes.

=== "Maven Java 11+"
```xml hl_lines="3-7 16 18 24-27"
<dependencies>
...
<dependency>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
<version>{{ powertools.version }}</version>
</dependency>
...
</dependencies>
...
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
<build>
<plugins>
...
<plugin>
<groupId>dev.aspectj</groupId>
<artifactId>aspectj-maven-plugin</artifactId>
<version>1.13.1</version>
<configuration>
<source>11</source> <!-- or higher -->
<target>11</target> <!-- or higher -->
<complianceLevel>11</complianceLevel> <!-- or higher -->
<aspectLibraries>
<aspectLibrary>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
</aspectLibrary>
</aspectLibraries>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
```

```xml hl_lines="3-7 16 18 24-27"
<dependencies>
...
<dependency>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
<version>{{ powertools.version }}</version>
</dependency>
...
</dependencies>
...
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
<build>
<plugins>
...
<plugin>
<groupId>dev.aspectj</groupId>
<artifactId>aspectj-maven-plugin</artifactId>
<version>1.13.1</version>
<configuration>
<source>11</source> <!-- or higher -->
<target>11</target> <!-- or higher -->
<complianceLevel>11</complianceLevel> <!-- or higher -->
<aspectLibraries>
<aspectLibrary>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
</aspectLibrary>
</aspectLibraries>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
```

=== "Maven Java 1.8"

Expand Down
1 change: 1 addition & 0 deletions docs/utilities/parameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -544,6 +544,7 @@ To simplify the use of the library, you can chain all method calls before a get.
.withTransformation(json) // json is a static import from Transformer.json
.withDecryption() // enable decryption of the parameter value
.get("/my/param", MyObj.class); // finally get the value
```

### Create your own Provider
You can create your own custom parameter store provider by implementing a handful of classes:
Expand Down
Loading