Merge missing changes

scottgerring · scottgerring · commit 77f916a934b9 · 2023-11-21T18:37:48.000+01:00
diff --git a/README.md b/README.md
@@ -11,19 +11,11 @@ Powertools for AWS Lambda (Java) is a developer toolkit to implement Serverless
 
 **[📜Documentation](https://docs.powertools.aws.dev/lambda-java/)** | **[Feature request](https://github.com/aws-powertools/powertools-lambda-java/issues/new?assignees=&labels=feature-request%2C+triage&template=feature_request.md&title=)** | **[🐛Bug Report](https://github.com/aws-powertools/powertools-lambda-java/issues/new?assignees=&labels=bug%2C+triage&template=bug_report.md&title=)** | **[Detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-aws-lambda-powertools-java/)**
 
-### Java Compatibility
-Powertools for AWS Lambda (Java) supports all Java version from 8 up to 21 as well as the 
-[corresponding Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). 
-
-AspectJ does not yet support Java 21 [[1]](https://github.com/eclipse-aspectj/aspectj/issues/260), [[2]](https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md).
-If you need to use aspects - either  Powertools features leveraging aspects or other libraries - you should use the JDK 17 compiler and target either the Java 17 or Java 21
-Lambda runtimes. 
-
-### Installation
+## Installation
 
 Powertools for AWS Lambda (Java) is available in Maven Central. You can use your favourite dependency management tool to install it
 
-#### Maven:
+### Maven:
 ```xml
 <dependencies>
     ...
@@ -198,6 +190,33 @@ Next, configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lam
 ```
 </details>
 
+### Java Compatibility
+Powertools for AWS Lambda (Java) supports all Java version from 8 up to 21 as well as the
+[corresponding Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
+For the modules that provide annotations, Powertools for AWS Lambda (Java) leverages the **aspectj** library.
+You may need to add the good version of `aspectjrt` to your dependencies based on the JDK used for building your function:
+
+```xml
+<dependency>
+    <groupId>org.aspectj</groupId>
+    <artifactId>aspectjrt</artifactId>
+    <version>1.9.??</version>
+</dependency>
+```
+
+<details>
+    <summary><b>JDK - aspectj dependency matrix</b></summary>
+
+| JDK version | aspectj version |
+|-------------|-----------------|
+| `1.8`       | `1.9.7`         |
+| `11-17`     | `1.9.20.1`      |
+| `21`        | `1.9.21`        |
+
+More info [here](https://github.com/aws-powertools/powertools-lambda-java/pull/1519/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R191).
+
+</details>
+
 ## Examples
 
 See the latest release of the **[examples](https://github.com/aws-powertools/powertools-lambda-java/tree/v1.18.0/examples)** for example projects showcasing usage of different utilities.
diff --git a/docs/core/logging.md b/docs/core/logging.md
@@ -596,12 +596,18 @@ via `samplingRate` attribute on annotation.
                     POWERTOOLS_LOGGER_SAMPLE_RATE: 0.5
     ```
 
-## AWS Lambda Advanced Logging Controls
-With AWS [Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced), you can control the output format of your logs as either `TEXT` or `JSON` and specify the minimum accepted log level for your application. 
-Regardless of the output format setting in Lambda, Powertools for AWS Lambda will always output JSON formatted logging messages.
+## AWS Lambda Advanced Logging Controls (ALC)
 
-When you have this feature enabled, log messages that don’t meet the configured log level are discarded by Lambda. 
-For example, if you set the minimum log level to `WARN`, you will only receive `WARN` and `ERROR` messages in your AWS CloudWatch Logs, all other log levels will be discarded by Lambda.
+!!!question "When is it useful?"
+    When you want to set a logging policy to drop informational or verbose logs for one or all AWS Lambda functions, regardless of runtime and logger used.
+
+<!-- markdownlint-disable MD013 -->
+With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
+
+When enabled, you should keep `Logger` and ALC log level in sync to avoid data loss.
+
+Here's a sequence diagram to demonstrate how ALC will drop both `INFO` and `DEBUG` logs emitted from `Logger`, when ALC log level is stricter than `Logger`.
+<!-- markdownlint-enable MD013 -->
 
 ```mermaid
 sequenceDiagram
@@ -610,29 +616,29 @@ sequenceDiagram
     participant Application Logger
 
     Note over Lambda service: AWS_LAMBDA_LOG_LEVEL="WARN"
+    Note over Application Logger: POWERTOOLS_LOG_LEVEL="DEBUG"
+
     Lambda service->>Lambda function: Invoke (event)
     Lambda function->>Lambda function: Calls handler
-    Lambda function->>Application Logger: logger.warn("Something happened")
+    Lambda function->>Application Logger: logger.error("Something happened")
     Lambda function-->>Application Logger: logger.debug("Something happened")
     Lambda function-->>Application Logger: logger.info("Something happened")
-    
-    Lambda service->>Lambda service: DROP INFO and DEBUG logs
-
+    Lambda service--xLambda service: DROP INFO and DEBUG logs
     Lambda service->>CloudWatch Logs: Ingest error logs
 ```
 
-Logger will automatically listen for the `AWS_LAMBDA_LOG_FORMAT` and `AWS_LAMBDA_LOG_LEVEL` environment variables, and change behaviour if they’re found to ensure as much compatibility as possible.
-
 ### Priority of log level settings in Powertools for AWS Lambda
 
-When the Advanced Logging Controls feature is enabled, we are unable to increase the minimum log level below the `AWS_LAMBDA_LOG_LEVEL` environment variable value, see [AWS Lambda service documentation](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-log-level) for more details.
-
 We prioritise log level settings in this order:
 
 1. `AWS_LAMBDA_LOG_LEVEL` environment variable
 2. `POWERTOOLS_LOG_LEVEL` environment variable
 
-In the event you have set `POWERTOOLS_LOG_LEVEL` to a level lower than the ACL setting, Powertools for AWS Lambda will output a warning log message informing you that your messages will be discarded by Lambda.
+If you set `Logger` level lower than ALC, we will emit a warning informing you that your messages will be discarded by Lambda.
+
+> **NOTE**
+>
+> With ALC enabled, we are unable to increase the minimum log level below the `AWS_LAMBDA_LOG_LEVEL` environment variable value, see [AWS Lambda service documentation](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-log-level){target="_blank"} for more details.
 
 ### Timestamp format
 
diff --git a/docs/index.md b/docs/index.md
@@ -15,14 +15,6 @@ Powertools for AWS Lambda (Java) is a suite of utilities for AWS Lambda Function
     Check out [this detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-aws-lambda-powertools-java/) with a practical example. To dive deeper, 
     the [Powertools for AWS Lambda (Java) workshop](https://catalog.us-east-1.prod.workshops.aws/workshops/a7011c82-e4af-4a52-80fa-fcd61f1dacd9/en-US/introduction) is a great next step.
 
-???+ tip "Java Compatability"
-    Powertools for AWS Lambda (Java) supports all Java version from 8 up to 21 as well as the
-    [corresponding Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
-
-    AspectJ does not yet support Java 21 [[1]](https://github.com/eclipse-aspectj/aspectj/issues/260), [[2]](https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md).
-    If you need to use aspects - either  Powertools features leveraging aspects or other libraries - you should use the JDK 17 compiler and target either the Java 17 or Java 21
-    Lambda runtimes. 
-
 ## Tenets
 
 This project separates core utilities that will be available in other runtimes vs general utilities that might not be available across all runtimes.
@@ -282,6 +274,41 @@ Depending on your version of Java (either Java 1.8 or 11+), the configuration sl
     Under the hood, `org.codehaus.mojo:aspectj-maven-plugin` is based on AspectJ 1.9.7, 
     while `dev.aspectj:aspectj-maven-plugin` is based on AspectJ 1.9.8, compiled for Java 11+.
 
+### Java Compatibility
+Powertools for AWS Lambda (Java) supports all Java version from 8 up to 21 as well as the
+[corresponding Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
+
+For the following modules, Powertools for AWS Lambda (Java) leverages the **aspectj** library to provide annotations:
+- Logging
+- Metrics
+- Tracing
+- Parameters
+- Idempotency
+- Validation
+- Large messages
+
+
+You may need to add the good version of `aspectjrt` to your dependencies based on the jdk used for building your function:
+
+```xml
+<dependency>
+    <groupId>org.aspectj</groupId>
+    <artifactId>aspectjrt</artifactId>
+    <version>1.9.??</version>
+</dependency>
+```
+
+Use the following [dependency matrix](https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md) between this library and the JDK:
+
+| JDK version | aspectj version |
+|-------------|-----------------|
+| `1.8`       | `1.9.7`         |
+| `11-17`     | `1.9.20.1`      |
+| `21`        | `1.9.21`        |
+
+_Note: 1.9.21 is not yet available and Java 21 not yet officially supported by aspectj, but you can already use the `1.9.21.M1`_
+
+
 ## Environment variables
 
 !!! info
diff --git a/pom.xml b/pom.xml
@@ -73,7 +73,6 @@
         <maven.compiler.target>1.8</maven.compiler.target>
         <log4j.version>2.20.0</log4j.version>
         <jackson.version>2.15.3</jackson.version>
-        <aspectj.version>1.9.7</aspectj.version>
         <aws.sdk.version>2.21.0</aws.sdk.version>
         <aws.xray.recorder.version>2.14.0</aws.xray.recorder.version>
         <payloadoffloading-common.version>2.1.3</payloadoffloading-common.version>
@@ -82,6 +81,7 @@
         <lambda.events.version>3.11.2</lambda.events.version>
         <lambda.serial.version>1.1.2</lambda.serial.version>
         <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
+        <aspectj.version>1.9.7</aspectj.version>
         <aspectj-maven-plugin.version>1.13.1</aspectj-maven-plugin.version>
         <maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
         <jacoco-maven-plugin.version>0.8.10</jacoco-maven-plugin.version>
@@ -514,6 +514,7 @@
                 </plugins>
             </build>
         </profile>
+
         <profile>
             <id>jdk16</id>
             <activation>
diff --git a/powertools-e2e-tests/handlers/logging/pom.xml b/powertools-e2e-tests/handlers/logging/pom.xml
@@ -17,6 +17,10 @@
             <groupId>software.amazon.lambda</groupId>
             <artifactId>powertools-logging</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.aspectj</groupId>
+            <artifactId>aspectjrt</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.amazonaws</groupId>
             <artifactId>aws-lambda-java-events</artifactId>
diff --git a/powertools-e2e-tests/handlers/pom.xml b/powertools-e2e-tests/handlers/pom.xml
@@ -43,7 +43,11 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
-
+            <dependency>
+                <groupId>org.aspectj</groupId>
+                <artifactId>aspectjrt</artifactId>
+                <version>${aspectj.version}</version>
+            </dependency>
             <dependency>
                 <groupId>software.amazon.lambda</groupId>
                 <artifactId>powertools-logging</artifactId>
@@ -99,11 +103,6 @@
                 <artifactId>log4j-slf4j2-impl</artifactId>
                 <version>${log4j.version}</version>
             </dependency>
-            <dependency>
-                <groupId>org.aspectj</groupId>
-                <artifactId>aspectjrt</artifactId>
-                <version>${aspectj.version}</version>
-            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -132,11 +131,11 @@
                         </execution>
                     </executions>
                     <dependencies>
-                        <dependency>
-                            <groupId>org.apache.logging.log4j</groupId>
-                            <artifactId>log4j-transform-maven-shade-plugin-extensions</artifactId>
-                            <version>0.1.0</version>
-                        </dependency>
+                      <dependency>
+                        <groupId>org.apache.logging.log4j</groupId>
+                        <artifactId>log4j-transform-maven-shade-plugin-extensions</artifactId>
+                        <version>0.1.0</version>
+                       </dependency>
                     </dependencies>
                 </plugin>
                 <plugin>
@@ -154,6 +153,7 @@
                     <artifactId>aspectj-maven-plugin</artifactId>
                     <version>${aspectj.plugin.version}</version>
                     <configuration>
+                        <verbose>true</verbose>
                         <source>${maven.compiler.source}</source>
                         <target>${maven.compiler.target}</target>
                         <complianceLevel>${maven.compiler.target}</complianceLevel>
@@ -162,7 +162,6 @@
                     </configuration>
                     <executions>
                         <execution>
-                            <phase>process-sources</phase>
                             <goals>
                                 <goal>compile</goal>
                                 <goal>test-compile</goal>
@@ -182,15 +181,34 @@
     </build>
 
     <profiles>
+        <!-- https://github.com/eclipse-aspectj/aspectj/blob/master/docs/dist/doc/JavaVersionCompatibility.md -->
         <profile>
-            <id>jdk8</id>
+            <id>jdk8to16</id>
             <activation>
-                <jdk>(,11)</jdk> <!-- < 11 -->
+                <jdk>[1.8,16]</jdk>
             </activation>
             <properties>
                 <aspectj.version>1.9.7</aspectj.version>
             </properties>
         </profile>
+        <profile>
+            <id>jdk17to20</id>
+            <activation>
+                <jdk>[17,20]</jdk>
+            </activation>
+            <properties>
+                <aspectj.version>1.9.20.1</aspectj.version>
+            </properties>
+        </profile>
+        <profile>
+            <id>jdk21</id>
+            <activation>
+                <jdk>[21,)</jdk>
+            </activation>
+            <properties>
+                <aspectj.version>1.9.21.M1</aspectj.version>
+            </properties>
+        </profile>
     </profiles>
 
 </project>
diff --git a/powertools-e2e-tests/src/test/java/software/amazon/lambda/powertools/testutils/Infrastructure.java b/powertools-e2e-tests/src/test/java/software/amazon/lambda/powertools/testutils/Infrastructure.java
@@ -114,7 +114,6 @@ public class Infrastructure {
     private final String queue;
     private final String kinesisStream;
     private final String largeMessagesBucket;
-    private final JavaRuntime lambdaRuntimeVersion;
     private String ddbStreamsTableName;
     private String functionName;
     private Object cfnTemplate;
@@ -125,7 +124,6 @@ private Infrastructure(Builder builder) {
         this.tracing = builder.tracing;
         this.envVar = builder.environmentVariables;
         this.runtime = builder.runtime;
-        this.lambdaRuntimeVersion = builder.lambdaRuntimeVersion;
         this.timeout = builder.timeoutInSeconds;
         this.pathToFunction = builder.pathToFunction;
         this.idempotencyTable = builder.idemPotencyTable;
@@ -213,7 +211,6 @@ private Stack createStackWithLambda() {
                 "cd " + pathToFunction +
                         " && timeout -s SIGKILL 5m mvn clean install -ff " +
                         " -Dmaven.test.skip=true " +
-                        " -Dmaven.resources.skip=true " +
                         " -Dmaven.compiler.source=" + runtime.getMvnProperty() +
                         " -Dmaven.compiler.target=" + runtime.getMvnProperty() +
                         " && cp /asset-input/" + pathToFunction + "/target/function.jar /asset-output/"
@@ -250,7 +247,7 @@ private Stack createStackWithLambda() {
                 .handler("software.amazon.lambda.powertools.e2e.Function::handleRequest")
                 .memorySize(1024)
                 .timeout(Duration.seconds(timeout))
-                .runtime(lambdaRuntimeVersion.getCdkRuntime())
+                .runtime(runtime.getCdkRuntime())
                 .environment(envVar)
                 .tracing(tracing ? Tracing.ACTIVE : Tracing.DISABLED)
                 .build();
@@ -507,11 +504,9 @@ public static class Builder {
         private String queue;
         private String kinesisStream;
         private String ddbStreamsTableName;
-        private JavaRuntime lambdaRuntimeVersion;
 
         private Builder() {
             runtime = mapRuntimeVersion("JAVA_VERSION");
-            lambdaRuntimeVersion = mapRuntimeVersion("JAVA_LAMBDA_RUNTIME_VERSION");
         }
 
 
@@ -520,7 +515,7 @@ private JavaRuntime mapRuntimeVersion(String environmentVariableName) {
             String javaVersion = System.getenv(environmentVariableName); // must be set in GitHub actions
             JavaRuntime ret = null;
             if (javaVersion == null) {
-                throw new IllegalArgumentException("JAVA_LAMBDA_RUNTIME_VERSION is not set");
+                throw new IllegalArgumentException(environmentVariableName + " is not set");
             }
             if (javaVersion.startsWith("8")) {
                 ret = JavaRuntime.JAVA8AL2;
