Merge branch 'main' into dependabot/maven/aws.xray.recorder.version-2.18.3

Author: phipag

Priming.md

@@ -0,0 +1,59 @@
+# Automatic Priming for AWS Lambda Powertools Java
+
+## Table of Contents
+- [Overview](#overview)
+- [Implementation Steps](#general-implementation-steps)
+- [Known Issues](#known-issues-and-solutions)
+- [Reference Implementation](#reference-implementation)
+
+## Overview
+Priming is the process of preloading dependencies and initializing resources during the INIT phase, rather than during the INVOKE phase to further optimize startup performance with SnapStart. 
+This is required because Java frameworks that use dependency injection load classes into memory when these classes are explicitly invoked, which typically happens during Lambda’s INVOKE phase.
+
+This documentation provides guidance for automatic class priming in Powertools for AWS Lambda Java modules.
+
+
+## Implementation Steps
+Classes are proactively loaded using Java runtime hooks which are part of the open source [CRaC (Coordinated Restore at Checkpoint) project](https://openjdk.org/projects/crac/).
+Implementations across the project use the `beforeCheckpoint()` hook, to prime Snapstart-enabled Java functions via Class Priming.
+In order to generate the `classloaded.txt` file for a Java module in this project, follow these general steps.
+
+1. **Add Maven Profile**
+    - Add maven test profile with the following VM argument for generating classes loaded files. 
+   ```shell
+      -Xlog:class+load=info:classesloaded.txt
+      ```
+    - You can find an example of this in `generate-classesloaded-file` profile in this [pom.xml](powertools-metrics/pom.xml).
+
+2. **Generate classes loaded file**
+    - Run tests with `-Pgenerate-classesloaded-file` profile.
+   ```shell
+   mvn -Pgenerate-classesloaded-file clean test
+   ```
+   - This will generate a file named `classesloaded.txt` in the target directory of the module.
+
+3. **Cleanup the file**
+    - The classes loaded file generated in Step 2 has the format
+   `[0.054s][info][class,load] java.lang.Object source: shared objects file` 
+   but we are only interested in `java.lang.Object` - the fully qualified class name.
+    - To strip the lines to include only the fully qualified class name, 
+      Use the following regex to replace with empty string.
+      - `^\[[\[\]0-9.a-z,]+ ` (to replace the left part)
+      - `( source: )[0-9a-z :/._$-]+` (to replace the right part)
+
+4. **Add file to resources**
+    -  Move the cleaned-up file to the corresponding `src/main/resources` directory of the module. See [example](powertools-metrics/src/main/resources/classesloaded.txt).
+
+5. **Register and checkpoint**
+    - A class, usually the entry point of the module, should register the CRaC resource in the constructor. [Example](powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsFactory.java)
+      - Note that AspectJ aspect is not suitable for this purpose, as it does not work with CRaC.
+    - Add the `beforeCheckpoint()` hook in the same class to invoke `ClassPreLoader.preloadClasses()`. The `ClassPreLoader` class is implemented in `powertools-common` module.
+    - This will ensure that the classes are already pre-loaded by the Snapstart RESTORE operation leading to a shorter INIT duration.
+  
+
+## Known Issues
+- This is a manual process at the moment, but it can be automated in the future.
+- `classesloaded.txt` file includes test classes as well because the file is generated while running tests. This is not a problem because all the classes that are not found are ignored by `ClassPreLoader.preloadClasses()`. Also `beforeCheckpoint()` hook is not time-sensitive, it only runs once when a new Lambda version gets published. 
+
+## Reference Implementation
+Working example is available in the [powertools-metrics](powertools-metrics/src/main/java/software/amazon/lambda/powertools/metrics/MetricsFactory.java). 

docs/Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material@sha256:0bfdba448e93984191246f7a28abeacc79f789e7e9cf0c639a48fe4365e880a7
+FROM squidfunk/mkdocs-material@sha256:bb7b015690d9fb5ef0dbc98ca3520f153aa43129fb96aec5ca54c9154dc3b729
 
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt

examples/powertools-examples-batch/deploy/sqs/template.yml

@@ -65,6 +65,7 @@ Resources:
   DemoSQSSenderFunction:
     Type: AWS::Serverless::Function
     Properties:
+      Tracing: Active
       CodeUri: ../..
       Handler: org.demo.batch.sqs.SqsBatchSender::handleRequest
       Environment:
@@ -173,7 +174,6 @@ Resources:
               Action:
                 - s3:PutObject
               Resource: !Sub ${Bucket.Arn}/*
-
       Events:
         MySQSEvent:
           Type: SQS

examples/powertools-examples-batch/src/main/java/org/demo/batch/sqs/AbstractSqsBatchHandler.java

@@ -14,21 +14,22 @@
 
 package org.demo.batch.sqs;
 
-import com.amazonaws.services.lambda.runtime.Context;
-import com.fasterxml.jackson.databind.ObjectMapper;
 import java.io.File;
 import java.io.IOException;
 import java.util.Arrays;
 import java.util.Random;
+
 import org.demo.batch.model.Product;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.slf4j.MDC;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
 import software.amazon.awssdk.core.sync.RequestBody;
 import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
 import software.amazon.awssdk.services.s3.S3Client;
 import software.amazon.awssdk.services.s3.model.PutObjectRequest;
-import software.amazon.lambda.powertools.logging.Logging;
 import software.amazon.lambda.powertools.tracing.Tracing;
 import software.amazon.lambda.powertools.tracing.TracingUtils;
 
@@ -43,23 +44,23 @@ public class AbstractSqsBatchHandler {
      * Simulate some processing (I/O + S3 put request)
      * @param p deserialized product
      */
-    @Logging
     @Tracing
     protected void processMessage(Product p) {
         TracingUtils.putAnnotation("productId", p.getId());
         TracingUtils.putAnnotation("Thread", Thread.currentThread().getName());
         MDC.put("product", String.valueOf(p.getId()));
         LOGGER.info("Processing product {}", p);
 
-        char c = (char)(r.nextInt(26) + 'a');
+        char c = (char) (r.nextInt(26) + 'a');
         char[] chars = new char[1024 * 1000];
         Arrays.fill(chars, c);
         p.setName(new String(chars));
         try {
-            File file = new File("/tmp/"+p.getId()+".json");
+            File file = new File("/tmp/" + p.getId() + ".json");
             mapper.writeValue(file, p);
             s3.putObject(
-                    PutObjectRequest.builder().bucket(bucket).key(p.getId()+".json").build(), RequestBody.fromFile(file));
+                    PutObjectRequest.builder().bucket(bucket).key(p.getId() + ".json").build(),
+                    RequestBody.fromFile(file));
         } catch (IOException e) {
             throw new RuntimeException(e);
         } finally {

examples/powertools-examples-cloudformation/pom.xml

@@ -14,7 +14,7 @@
         <maven.compiler.target>11</maven.compiler.target>
         <lambda.core.version>1.3.0</lambda.core.version>
         <lambda.events.version>3.16.1</lambda.events.version>
-        <aws.sdk.version>2.32.5</aws.sdk.version>
+        <aws.sdk.version>2.32.10</aws.sdk.version>
         <aspectj.version>1.9.20.1</aspectj.version>
 
     </properties>

examples/powertools-examples-core-utilities/kotlin/.gitignore

@@ -0,0 +1 @@
+bin/

examples/powertools-examples-idempotency/src/main/java/helloworld/App.java

@@ -34,6 +34,7 @@
 import software.amazon.lambda.powertools.idempotency.Idempotent;
 import software.amazon.lambda.powertools.idempotency.persistence.dynamodb.DynamoDBPersistenceStore;
 import software.amazon.lambda.powertools.logging.Logging;
+import software.amazon.lambda.powertools.tracing.Tracing;
 import software.amazon.lambda.powertools.utilities.JsonConfig;
 
 public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
@@ -91,6 +92,7 @@ public App(DynamoDbClient client) {
      */
     @Idempotent // The magic is here!
     @Logging(logEvent = true)
+    @Tracing
     public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
         Map<String, String> headers = new HashMap<>();
 
@@ -130,6 +132,7 @@ public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEv
      * @return The contents of the given URL
      * @throws IOException
      */
+    @Tracing
     private String getPageContents(String address) throws IOException {
         URL url = new URL(address);
         try (BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream(), StandardCharsets.UTF_8))) {

examples/powertools-examples-idempotency/src/main/resources/log4j2.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+    <Appenders>
+        <Console name="JsonAppender" target="SYSTEM_OUT">
+            <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>