Skip to content

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

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

Merged
scottgerring 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 1 commit
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
92 changes: 90 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,91 @@ 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.
Comment thread
jreijn marked this conversation as resolved.
Outdated
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.
Comment thread
jreijn marked this conversation as resolved.
Outdated

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 low level libraries for all target runtimes (linux, macos, windows, etc).

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>1.18.0</version>
<exclusions>
<exclusion>
<groupId>software.amazon.awssdk</groupId>
<artifactId>url-connection-client</artifactId>
</exclusion>
</exclusions>
</dependency>
```
Next to adding the `aws-crt-client` and excluding the `aws-crt` dependency (contain all runtime libraries) it's required to set a specific runtime version of the `aws-crt` dependency by specifying the classifier for your specific target runtime.
Comment thread
jreijn marked this conversation as resolved.
Outdated
Specifying the specific target runtime makes sure all other target runtimes are excluded from the jar file, which will result in the benefit of improved cold start times.
Comment thread
jeromevdl marked this conversation as resolved.
Outdated
Comment thread
jreijn marked this conversation as resolved.
Outdated

```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>
```

After configuring the dependencies it's required to specify the aws sdk http client.
Comment thread
jreijn marked this conversation as resolved.
Outdated
Most modules support a custom sdk client by leveraging the `.withClient()` method on the for instance the Provider singleton:
Copy link
Copy Markdown
Contributor

@jeromevdl jeromevdl Mar 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

something missing here...

Copy link
Copy Markdown
Contributor Author

@jreijn jreijn Mar 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've tried to clarify it a bit more. I noticed I focussed too much on the parameters module, but other modules also use the url-connection client. Turned it into an example for a module and described that it depends on the PT module in use how to further configure the http 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.lambda.powertools.parameters.ssm.SSMProvider;

public class RequestHandlerWithParams implements RequestHandler<String, String> {

// Get an instance of the SSMProvider. We can provide a custom client here if we want,
// for instance to use the aws crt http client.
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;
}
}
```
It has been considered to make the `aws-crt-client` 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),
Comment thread
jreijn marked this conversation as resolved.
Outdated
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